Compare commits

Author SHA1 Message Date
Job79andClaude Opus 5.5 0a68a046ef fix: check out with git again
actions/checkout needs Node.js in every job and fetches the action from
GitHub. Four lines of git need neither.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 17:40:59 +00:00
Job79andClaude Opus 5.5 e0cd5db5c5 fix: use Node.js 26 for actions/checkout
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 17:27:43 +00:00
Job79andClaude Opus 5.5 3793cb0f31 fix: check out with actions/checkout
gitea-runner 6 removed builtin:checkout. With Node.js in the job,
actions/checkout works.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 17:05:15 +00:00
Job79andClaude Opus 5.5 34be2ef89f docs: say that gitea-runner 6 removed builtin:checkout
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 17:01:03 +00:00
Job79andClaude Opus 5.5 94fd5d1ce9 fix: check out with git, sign local builds with a test key
gitea-runner 6 has no builtin:checkout, and plain Fedora has no Node.js
for actions/checkout, so the workflow fetches the commit with git.
Setting permissions: keeps read access for that and asks for package
writes.

mkosi genkey won't replace mkosi.crt, so the docs now sign local builds
with a test key in mkosi.local.conf, which also covers the PCR and
verity keys.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 16:07:45 +00:00
Job79andClaude Opus 5.5 738a902b2d docs: drop the trust step, which agent.conf already does
os / os (push) Waiting to run
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 16:48:30 +01:00
Job79andClaude Opus 5.5 3a4a9f715a fix: run Remote Control in ~/work, which Claude can trust
os / os (push) Waiting to run
Claude never saves trust for a home directory, so claude-remote.service
now runs in ~/work, which tmpfiles makes and pre-trusts in .claude.json.
Its status screen on stdout no longer floods the journal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 16:47:45 +01:00
Job79andClaude Opus 5.5 1707500c05 refactor: rename to agentos, hand-picked /etc, user presets at first boot
os / os (push) Waiting to run
- Rename the image from agent to agentos (ImageId, hostname, CI, docs).
- mkosi.finalize only copies /etc to /usr/share/factory/etc. The hand-written
  tmpfiles.d/factory-etc.conf links the 24 entries the image needs.
- /etc/systemd is writable: PID 1 applies the system presets at first boot
  and preset-global.service the user presets, as in ParticleOS.
- claude-remote runs in the user manager of agent, enabled by a user preset.
- Root has no /var subvolume, and the verity partitions shrink to 16M.
- Style pass over comments, CLAUDE.md and AGENTS.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 15:48:42 +01:00
Job79andClaude Opus 5.5 186d133cbc fix: keep the mkosi workspace off overlayfs in the test container
os / os (push) Canceled after 0s
mkosi's copy_tree() leaves out all xattrs when it copies a tree with SELinux
labels to overlayfs. In the podman test container the workspace was in
/var/tmp on the container's overlayfs, and the cached tree has the host's
SELinux labels, so newuidmap and newgidmap lost their file capabilities and
rootless podman failed in the VM. A volume at /var/tmp avoids that.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V27snrrx9tfCQvBpqtSPn3
2026-11-21 20:53:45 +01:00
Job79andClaude Opus 5.5 5255656258 refactor: style pass, tools tree and fixes from a test build
os / os (push) Canceled after 0s
- Follow AGENTS.md style: headers start with the file's name, short
  notes are full sentences, comments within 80 columns.
- Build with mkosi's tools tree, pinned to the image's release
  (ToolsTreeRelease=%r): rawhide's repositories made the image rawhide.
- Incremental builds with mkosi.cache/ for faster local rebuilds.
- Hostname= instead of systemd.hostname= on the kernel command line.
- mkosi.finalize: bash, no cd, and L+ for /etc/systemd. PID 1 applies
  the presets at first boot and made /etc/systemd/system, which blocked
  the link, so /etc/systemd/user (the user's D-Bus) was missing.
- Disable homed, userdbd and nsresourced with presets instead of
  deleting their units. Drop modules the kernel has built in.
- mkosi.version adds the git commit to the version.
- One dev container per worktree or session in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 20:37:26 +01:00
Job79andClaude Opus 5.5 c80e843cb5 feat: ParticleOS-like layout: /usr image, encrypted btrfs root
The image now holds only the ESP and a verity-protected /usr (A/B). At
first boot, systemd-repart in the initrd makes the root filesystem: btrfs,
encrypted with a TPM key sealed to the signed PCR 11 policy, with /var as
its own subvolume. A TPM is required. systemd.image_policy= accepts only
an encrypted root and a verity-checked /usr, and FactoryReset=yes lets
factory-reset.target wipe it.

/etc is writable but nearly empty: mkosi.finalize keeps the build's /etc
in /usr/share/factory/etc and systemd-tmpfiles links it in at boot. That
removes etc-shadow.mount, the host key on /var, fstab and /var/lib/agent.
/var now survives reboots.

systemd-firstboot replaces agent-setup: it asks for the root password on
the screen and offers a recovery key. Machines are named agent-???? from
the kernel command line. The user is now agent, with its home in
/home/agent and ssh keys in the default places. sshd.path starts sshd
only once root or agent has a key.

The test VM needs swtpm. The package cache moves to a podman volume
(AGENTS.md). No existing VMs can update to this layout.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 21:09:31 +01:00
Job79andClaude Opus 5.5 db8fb0d5a4 feat: root adds the ssh keys, mkosi ssh for the test VM
The setup no longer asks for an ssh key. Root logs in on the console and
adds keys for claude and root to /var/lib/agent. Root may log in with
ssh, and its home is a tmpfs that is wiped at every boot. The test VM
uses mkosi ssh instead of a forwarded port, so the agent.ssh-key
credential is gone.

Also mount /var with noatime, move STYLE.md into AGENTS.md and rewrite
comments to start with the name of what they describe.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 19:10:54 +01:00
Job79andClaude Opus 5.5 8aeb448936 docs: how to measure a normal boot of the test VM
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:09:15 +01:00
Job79andClaude Opus 5.5 49ae3230ed perf: drop DAMON reclaim
It sampled memory every 5ms, always on, which woke the VM ~400 times a
second at idle instead of ~50. Memory the VM has used now stays with it
until it needs it again or reboots.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 20:52:00 +01:00
Job79andClaude Opus 5.5 9dc6dff880 ci: compress the root partition with zstd -9
-19 took 34s for 5% less than -9, which takes 6s. The erofs inside is
compressed already.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 20:39:53 +01:00
Job79andClaude Opus 5.5 08fccd6aaf ci: convert the qcow2 on several cores
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 20:38:45 +01:00
Job79andClaude Opus 5.5 6fdd32834f perf: raise systemd's mount rate limit at boot
systemd handles mount changes at most 5 times per second and holds back
mount jobs once it hits that. At boot this delayed mounting / in the
initrd and /var by up to a second each. Boot goes from ~4.7s to ~2.4s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 20:30:10 +01:00
Job79andClaude Opus 5.5 a98a110dc0 perf: keep systemd-boot-random-seed
It seeds the kernel's RNG at the next boot. Keeping it is worth the
wait for the ESP.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:56:10 +01:00
Job79andClaude Opus 5.5 71277dd4cd perf: ext4 for /var, drop systemd-boot-random-seed
xfs is a module in Fedora's kernel and takes ~0.5s to load, which held
up mounting /var. ext4 is built in. systemd-boot-random-seed waited ~1s
for the ESP to mount. Also remove /afs and /buildroot from the image and
give the test VM 4 CPUs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:55:19 +01:00
Job79andClaude Opus 5.5 144ce30757 test: give the test VM 8 CPUs
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:46:07 +01:00
Job79andClaude Opus 5.5 51272b708c build: keep downloaded packages in mkosi.pkgcache
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:36:23 +01:00
Job79andClaude Opus 5.5 2439f58279 docs: move testing details from README to AGENTS.md
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:33:00 +01:00
Job79andClaude Opus 5.5 3b791adc3d docs: list the mkosi container's needs instead of a Containerfile
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:18:50 +01:00
Job79andClaude Opus 5.5 e9b93b11a6 Merge branch 'mkosi-vm' into main
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:15:57 +01:00
Job79andClaude Opus 5.5 86f64a6304 perf: xfs for /var, lz4hc for the root erofs
xfs replaces ext4 on /var (no fsck pass, so fstab passno 0), and the
root erofs uses lz4hc, which decompresses faster than zstd.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:15:34 +01:00
Job79andClaude Opus 5.5 3146f54994 feat: run mkosi vm in a container with systemd
mkosi vm hangs where the host has no systemd, such as in a dev
container. The Containerfile runs systemd as init with mkosi and qemu,
so mkosi -f vm works through podman exec. Tested: builds and boots to
the login in about 105 seconds, of which booting takes about 6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 21:15:12 +01:00
Job79andClaude Opus 5.5 eb8e4b440a feat: boot a test VM with mkosi -f vm
The [Runtime] section of mkosi.conf sets up mkosi vm for testing: it
passes the setup credentials (mkosi.credentials/agent.ssh-key prints your
own ssh keys), forwards ssh to port 2222 and adds the serial console,
since systemd-stub ignores the console= mkosi passes under Secure Boot.

Untested: in a container without systemd, mkosi vm hangs before qemu
starts, because it can't create a systemd scope.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 21:02:43 +01:00
Job79andClaude Opus 5.5 ce1faca070 feat: unattended setup from credentials, rewrite README
agent-setup takes its answers from the credentials agent.password,
agent.hostname and agent.ssh-key when they are given, so a test VM boots
without typing. The README is shorter, explains the mkosi layout and
shows how to boot a test VM with these credentials. Also uploads the
manifest in the os workflow and ignores the test VM files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 21:02:29 +01:00
Job79 3ae080f978 chore: simplify comments in os.yml 2026-11-16 20:17:24 +01:00
Job79andClaude Opus 5.5 a1fc65ed21 style: apply STYLE.md to all files
Give every file a header (title, empty line, explanation), wrap comments
at 80 columns and keep them to the why. Only comments change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 20:14:06 +01:00
Job79 efb282bf7d Merge pull request 'docs: explain pipeline values, link style guide' (#1) from pipeline-comments into main
Reviewed-on: Job79/agent-mkosi#1
2026-11-16 19:09:28 +00:00
54 changed files with 550 additions and 462 deletions

No files matched your search

+32 -32
View File
@@ -1,49 +1,42 @@
# agent OS image # os.yml builds the OS image and publishes it as version "latest". VMs fetch
# the built images as updates (mkosi.extra/usr/lib/sysupdate.d). It runs on
# every push, weekly for package updates, and by hand for critical CVEs.
# #
# Builds the OS image and publishes it as version "latest". VMs fetch the build # Required values:
# images as updates (mkosi.extra/usr/lib/sysupdate.d). Runs on every push,
# weekly for package updates, and by hand for critical CVE's.
#
# Values used below:
# - PKG upload location, <server>/api/packages/<owner>/generic/
# agent/latest. Path= in mkosi.extra/usr/lib/sysupdate.d/
# *.transfer points at the same place.
# - AUTH the job's automatic token (gitea.token), which can write
# the owner's packages.
# - SECUREBOOT_KEY repository secret: the private key of mkosi.crt, written # - SECUREBOOT_KEY repository secret: the private key of mkosi.crt, written
# to mkosi.key. # to mkosi.key.
# - SIGNING_KEY repository secret: the armored private gpg key whose # - SIGNING_KEY repository secret: the armored private gpg key whose
# public half is mkosi.extra/usr/lib/systemd/ # public half is mkosi.extra/usr/lib/systemd/
# import-pubring.pgp, which systemd-sysupdate checks. # import-pubring.pgp, which systemd-sysupdate checks.
# - zstd -19 -T0 the root and verity partitions have a fixed size (1 GiB,
# 64 MiB) and are mostly zero padding: zstd shrinks them
# from ~1.1 GB to ~245 MB. -19 is ~11% smaller than the
# default -3, for ~35 s more build time. -T0 uses all
# cores; --rm deletes the .raw files. systemd-sysupdate
# decompresses .raw.zst as it downloads.
# - qemu-img -c agent.qcow2, the whole disk compressed, for creating new
# VMs (not for updates).
# - SHA256SUMS checksums of the update files, signed as SHA256SUMS.gpg
# (Verify=yes in sysupdate.d).
name: os name: os
on: on:
push: push:
branches: [main] branches: [main]
schedule: schedule:
- cron: "0 2 * * 0" # weekly (Sunday), picks up package updates - cron: "0 2 * * 0"
workflow_dispatch: # run by hand, e.g. for a CVE workflow_dispatch:
jobs: jobs:
os: os:
runs-on: linux runs-on: linux
env: # permissions lets gitea.token check out the repository and publish the
PKG: ${{ gitea.server_url }}/api/packages/${{ gitea.repository_owner }}/generic/agent/latest # package.
AUTH: "Authorization: token ${{ gitea.token }}" permissions:
contents: read
packages: write
steps: steps:
- name: Install tools - name: Install tools
run: dnf install -yq mkosi sbsigntools run: dnf install -yq mkosi git-core
# Check out fetches the commit with git, which needs no Node.js and no
# action from GitHub. gitea-runner 6 removed builtin:checkout.
- name: Check out - name: Check out
uses: builtin:checkout env:
AUTH: "Authorization: token ${{ gitea.token }}"
run: |
git init -q
git -c http.extraHeader="$AUTH" fetch -q --depth 1 \
"${{ gitea.server_url }}/${{ gitea.repository }}" "${{ gitea.sha }}"
git checkout -q FETCH_HEAD
- name: Build - name: Build
env: env:
KEY: ${{ secrets.SECUREBOOT_KEY }} KEY: ${{ secrets.SECUREBOOT_KEY }}
@@ -53,9 +46,10 @@ jobs:
- name: Compress - name: Compress
working-directory: mkosi.output working-directory: mkosi.output
run: | run: |
zstd -q --rm -T0 -19 agent_*.root-*.raw zstd -q --rm -9 agentos_*.usr-*.raw
qemu-img convert -c -O qcow2 "$(basename agent_*.efi .efi).raw" agent.qcow2 - name: Checksum
sha256sum agent_*.efi agent_*.root-*.raw.zst > SHA256SUMS working-directory: mkosi.output
run: sha256sum agentos_*.efi agentos_*.usr-*.raw.zst > SHA256SUMS
- name: Sign - name: Sign
working-directory: mkosi.output working-directory: mkosi.output
env: env:
@@ -64,10 +58,16 @@ jobs:
export GNUPGHOME=$(mktemp -d) export GNUPGHOME=$(mktemp -d)
gpg -q --batch --import <<< "$KEY" gpg -q --batch --import <<< "$KEY"
gpg -q --batch -o SHA256SUMS.gpg --detach-sign SHA256SUMS gpg -q --batch -o SHA256SUMS.gpg --detach-sign SHA256SUMS
- name: Build qcow2
working-directory: mkosi.output
run: qemu-img convert -c -O qcow2 "$(basename agentos_*.efi .efi).raw" agentos.qcow2
- name: Publish - name: Publish
working-directory: mkosi.output working-directory: mkosi.output
env:
PKG: ${{ gitea.server_url }}/api/packages/${{ gitea.repository_owner }}/generic/agentos/latest
AUTH: "Authorization: token ${{ gitea.token }}"
run: | run: |
curl -fsS -H "$AUTH" -X DELETE "$PKG" || true curl -fsS -H "$AUTH" -X DELETE "$PKG" || true
for f in agent_*.efi agent_*.root-*.raw.zst agent.qcow2 SHA256SUMS.gpg SHA256SUMS; do for f in agentos_*.efi agentos_*.usr-*.raw.zst agentos.qcow2 agentos_*.manifest SHA256SUMS.gpg SHA256SUMS; do
curl -fsS -o /dev/null -H "$AUTH" --upload-file "$f" "$PKG/$f" curl -fsS -o /dev/null -H "$AUTH" --upload-file "$f" "$PKG/$f"
done done
+3 -1
View File
@@ -1,2 +1,4 @@
mkosi.output/
mkosi.key mkosi.key
mkosi.output/
mkosi.cache/
mkosi.local.conf
+99
View File
@@ -0,0 +1,99 @@
# Agent notes
How to build and test this image as a coding agent. Follow [Style](#style) for
every change.
## Style
- Keep it simple. Prefer fewer files and fewer lines. Delete what isn't
needed. Write plain English in short sentences.
- Follow the defaults and conventions of each tool and language. Only set an
option when the default doesn't work.
- Each fact lives in one place. Elsewhere, refer to it instead of repeating it.
- Divide code and config into parts (files, directories, sections) that each
stand on their own: reading one part alone tells you what it does and why.
- Name each part for what it does. A part without a good name holds things
that don't belong together.
- A little copying beats a little dependency. Repeat a small piece rather than
share it or pull it in from elsewhere.
### File header
A file starts with a header, after the shebang if there is one. Leave it out
when the name already says it all, as with `.gitignore`. A part made of
many files, like a package, needs it in only one file. For example:
```sh
#!/bin/bash
# mkosi.version prints the build time in UTC (YYYYMMDDhhmm) and the git
# commit. Every build gets a higher version than the one before, which is how
# systemd-sysupdate tells that an update is newer. The commit tells which
# source an image was built from.
```
- The first sentence starts with the name of the part the file is, and says
what it does. That is the name the language or tool uses for it, such as a
file name or a package name.
- The rest says why, naming the files it works with by path.
Files that can't hold comments (JSON, `subuid`, `machine-id`) are explained in
the file that uses them.
### Comments
- Explain why, not what. Leave out comments that only repeat the code. Try to
write clean code instead of comments.
- Write full sentences that start with the name of what they describe:
`# ManifestFormat lists the packages and versions in the image.` or
`# link prints the tmpfiles line for /etc/$1.`
- Put a comment right above the line or block it is about. A short note on
one line may go at the end of that line, as a full sentence too.
- Separate paragraphs and lists with a line holding only the comment
character.
- Wrap comments at 80 columns.
## Testing
`mkosi vm` boots the image in qemu. It needs systemd on the host, so run mkosi
in a privileged podman container that boots systemd:
```sh
podman build -t mkosi-vm - <<'END'
FROM registry.fedoraproject.org/fedora:45
RUN dnf install -y mkosi git-core qemu-system-x86-core edk2-ovmf swtpm-tools \
virtiofsd openssh-clients socat
CMD ["/sbin/init"]
END
podman run -d --name mkosi --privileged --systemd=always -v <repo>:/repo \
-v mkosi-cache:/root/.cache/mkosi -v mkosi-work:/var/tmp -w /repo mkosi-vm
podman exec mkosi mkdir -p mkosi.cache
podman exec -d -t mkosi sh -c 'mkosi -i -f \
--kernel-command-line-extra=console=ttyS0 vm -- -serial chardev:console \
> mkosi.output/vm.log 2>&1'
podman exec mkosi mkosi ssh -- systemctl --failed
```
- mkosi signs with the test key of `mkosi.local.conf`
([README.md](README.md#development)), with paths as the container sees them.
- `mkosi -i` keeps the image with its packages installed in `mkosi.cache/`.
Rebuilds start from it and skip installing packages.
- The volume `mkosi-work` keeps mkosi's workspace in /var/tmp off overlayfs.
When mkosi copies files with SELinux labels to overlayfs, it drops all
xattrs. That removes the file capabilities of newuidmap and newgidmap, and
rootless podman fails in the VM.
- `mkosi vm` needs a terminal, hence `-d -t`. Its console goes to the log.
- The console of `mkosi vm` is hvc0, which the kernel can only use once the
initrd loads its driver. `console=ttyS0` also sends the kernel log to the
serial port, and `-serial chardev:console` sends that port to the same log.
The log then shows early errors too, such as a panic or an initrd that
can't find /usr. Arguments after `--` go to qemu.
- `mkosi ssh` runs a command as root once the VM has booted. For the user
`agent`, run `su - agent -c '<command>'`.
`mkosi.version` gives each run a new version, so `mkosi vm` without `-f` fails
with "has not been built yet". To boot an existing build again, pin its version
from `mkosi.output/agentos_<version>.raw`:
```sh
mkosi --image-version 202611171816.c80e843 vm
```
+52 -25
View File
@@ -1,42 +1,69 @@
# agent-mkosi # agentos
A VM that runs [Claude Code](https://claude.com/claude-code) in the background, packaged as a minimal Fedora image built with [mkosi](https://github.com/systemd/mkosi). You control Claude from claude.ai/code, the Claude app (Remote Control), or log in with ssh. A VM that runs [Claude Code](https://claude.com/claude-code) in the background.
It is a minimal Fedora image built with
[mkosi](https://github.com/systemd/mkosi). You control Claude from
claude.ai/code or the Claude app (Remote Control), or log in with ssh.
- **Resets at reboot:** the OS is read-only, so Claude can't change it, and Claude's home, `/tmp` and all containers are wiped at every boot. Only the setup answers and Claude's login survive (`/var/lib/agent`). - **Read-only OS:** `/usr` is read-only, so Claude can't change the OS. Secure
- **Claude as non-root, tools in containers:** Claude runs as the user `claude`, without root, and runs its toolchains in containers with rootless podman (also as `docker`). `/etc/claude-code/CLAUDE.md` tells it about the machine; `/etc/claude-code/managed-settings.json` lets it run without asking permission. The host has only git, ssh and basic command-line tools. Boot verifies the UKI (kernel, initrd and command line), which holds the
- **Self-updating:** like [git-runner-mkosi](../git-runner-mkosi): images are rebuilt weekly (also picking up the latest Claude Code) and on every push. Hosts download updates with systemd-sysupdate, check their signature (`SIGNING_KEY` secret), write them into a second root partition (A/B) and reboot into them daily at about 04:10. That reboot also resets Claude's work. A new version gets three tries to boot; if none gets through, systemd-boot goes back to the previous one. dm-verity hash that verifies `/usr`.
- **Read-only system:** systemd-boot starts a UKI that mounts the root filesystem, /etc and /usr included, from a read-only erofs partition checked by dm-verity. All state (Claude's home, its login, the root password, logs) lives on `/var`, its own partition. - **Encrypted with a TPM:** everything that isn't read-only, such as `/etc`,
- **Secure Boot:** systemd-boot and the UKIs are signed with our own key (`mkosi.crt`; the private key is the `SECUREBOOT_KEY` secret). systemd-boot enrolls it at first boot if the VM's firmware has no keys yet; the firmware then boots nothing else. `/var` and `/home`, is encrypted. The TPM unlocks it only for correctly signed
UKIs.
- **Easy to reset:** a factory reset wipes everything that isn't read-only, and
the VM sets itself up again as at first boot.
- **Tools in containers:** Claude runs as the user `agent`, without root, and
runs its toolchains in containers with podman.
- **Self-updating:** the image rebuilds weekly. A bad update rolls back by
itself.
## Install ## Install
Download [the disk image](https://git.plabble.org/api/packages/Job79/generic/agent/latest/agent.qcow2) (built by the `os` workflow), resize it to the disk size you want (/var grows to fill it) and boot it with UEFI in Secure Boot setup mode (no keys enrolled; in Proxmox, an EFI disk with "Pre-Enroll keys" unchecked), so it enrolls our key. The screen and the serial console ask for a root password, a hostname and an ssh public key for the user `claude`. Download [the disk image](https://git.plabble.org/api/packages/Job79/generic/agentos/latest/agentos.qcow2),
resize it to the disk size you want and boot it with UEFI and a TPM. At first
boot, the screen offers a recovery key for the encrypted disk and asks for a
root password. Then log in as root and put your ssh key in
`/home/agent/.ssh/authorized_keys` (for root: `~/.ssh/authorized_keys`), which
starts sshd. Run `claude` once as `agent` to sign in. The VM then shows up in
claude.ai/code and the Claude app under its hostname: `agentos-` and four hex
digits.
Then log Claude in once: To start over, run `systemctl start factory-reset.target` as root. It reboots
and wipes the root partition (`/etc`, `/var` and `/home`), and the VM sets
```sh itself up as at first boot.
ssh claude@<vm>
claude # trust the folder (your home), then /login with your Claude account
```
As soon as Claude is logged in, `claude-remote.service` starts `claude remote-control` in Claude's home, and the VM shows up in claude.ai/code and the Claude app under its hostname. Over ssh you can also run `claude` yourself. Logs: `journalctl -u claude-remote`.
## Development ## Development
`mkosi.conf` defines the OS (`mkosi.extra/` is copied to `/`, `mkosi.repart/` is the disk layout, `mkosi.sandbox/` adds the Claude Code package repository). When changing files, follow [STYLE.md](STYLE.md). `mkosi build` signs with `mkosi.key`, the private key of `mkosi.crt`, which
only CI has (the `SECUREBOOT_KEY` secret). `mkosi genkey` won't replace
`mkosi.crt`, so local builds sign with a test key. Make one:
```sh ```sh
mkosi build openssl req -new -x509 -newkey rsa:2048 -nodes -subj /CN=test \
-keyout ~/test.key -out ~/test.crt
``` ```
The build signs with `mkosi.key`: the `SECUREBOOT_KEY` secret, or for a local test a key of your own (`mkosi genkey` writes `mkosi.key` and `mkosi.crt`; don't commit them). and point `mkosi.local.conf` at it, which mkosi reads and git ignores:
`mkosi.output/` then holds the disk image (`agent_<version>.raw`), and the UKI and root partitions that the `os` workflow publishes as an update. To boot the disk image with Secure Boot (needs `qemu-kvm-core edk2-ovmf`; `OVMF_VARS.fd` has no keys, so it enrolls ours; ssh on port 2222): ```ini
[Validation]
SecureBootKey=~/test.key
SecureBootCertificate=~/test.crt
SignExpectedPcrKey=~/test.key
SignExpectedPcrCertificate=~/test.crt
VerityKey=~/test.key
VerityCertificate=~/test.crt
```
Then run `mkosi build`.
`mkosi.output/` then holds the disk image (`agentos_<version>.raw`) and the UKI
and /usr partitions that make up an update.
To build and boot a test VM:
```sh ```sh
qemu-img convert -O qcow2 mkosi.output/agent_<version>.raw test.qcow2 && qemu-img resize test.qcow2 40G mkosi -f vm # This opens the console. Log in as root, password root.
cp /usr/share/edk2/ovmf/OVMF_VARS.fd vars.fd mkosi ssh # This logs in as root with ssh, in another terminal.
qemu-kvm -m 8G -smp 4 -cpu host -nic user,model=virtio-net-pci,hostfwd=tcp::2222-:22 -drive file=test.qcow2,if=virtio -device virtio-balloon-pci,free-page-reporting=on \
-machine q35,smm=on -global driver=cfi.pflash01,property=secure,value=on \
-drive if=pflash,format=raw,readonly=on,file=/usr/share/edk2/ovmf/OVMF_CODE.secboot.fd -drive if=pflash,format=raw,file=vars.fd
``` ```
-43
View File
@@ -1,43 +0,0 @@
# Style guide
For everyone who changes this repository, people and AI agents alike.
## General
- Keep it simple. Prefer fewer files, fewer lines and the defaults. Delete what isn't needed.
- Each fact lives in one place. Elsewhere, refer to it by path instead of repeating it.
- Write plain English in short sentences.
## File header
Every file that allows comments starts with a header. It goes after the shebang, if there is one:
```sh
#!/bin/sh
# Image version
#
# The build time (UTC), so every build is newer than the last.
```
- Line 1 is a title: a few words, in sentence case, with no full stop.
- Then a line with only the comment character.
- Then what the file does and why, naming the files it works with by path.
Files that can't hold comments (JSON, `subuid`, `machine-id`) are explained in the file that uses
them or in the README.
## Comments
- Explain why, not what. Leave out comments that only repeat the code.
- Put a comment right above the line or block it is about.
- Wrap comments at 100 columns.
## Shell
- Use `#!/bin/sh` with `set -eu`. Switch to `#!/bin/bash` with `set -euo pipefail` only when the
script needs bash.
- Quote variables: `"$var"`.
## Config files
- Put one value per line in lists, with a comment explaining the less obvious entries.
+78 -80
View File
@@ -1,55 +1,74 @@
# agent: a Fedora VM image that runs Claude Code in the background, built with mkosi. # mkosi.conf builds agentos, a Fedora VM image that runs Claude Code. The
# mkosi.extra/ is copied to /, mkosi.repart/ defines the disk, mkosi.sandbox/ adds the Claude Code repo. # image holds a read-only /usr. The root filesystem, which holds the state,
# The root filesystem, /etc included, is read-only and replaced whole by updates; all state lives # is made at first boot.
# on /var. Claude can't change the OS: it runs its tools in containers. #
# The other parts of the build:
# - mkosi.extra/ is copied to /.
# - mkosi.repart/ defines the disk image: the ESP and the /usr partitions.
# - mkosi.extra/usr/lib/repart.d/ makes the root partition at first boot.
# - mkosi.finalize keeps /etc in /usr/share/factory/etc.
# - mkosi.sandbox/ adds the Claude Code package repository.
# - mkosi.version gives each build its version.
[Distribution] [Distribution]
Distribution=fedora Distribution=fedora
Release=45 Release=45
[Output] [Output]
Format=disk # Output writes agentos_<version>.* to mkosi.output/. The UKI and /usr
ImageId=agent # partitions are split into the files of an update.
ImageId=agentos
OutputDirectory=mkosi.output OutputDirectory=mkosi.output
# The UKI and root partitions are published as updates (systemd-sysupdate).
SplitArtifacts=uki,partitions SplitArtifacts=uki,partitions
ManifestFormat=json
[Content] [Content]
Bootable=yes # Content sets what goes into the image:
Bootloader=systemd-boot # - Hostname is agentos- and four hex digits of the machine ID.
# - kernel-core no drivers or firmware beyond what VMs need # - WithDocs leaves out man pages. The image has no man to read them.
# - systemd-container, gnupg2 systemd-pull, which systemd-sysupdate downloads with, and gpg, # - Packages lists the packages installed into the image.
# which it checks their signature with # - UnifiedKernelImageFormat names the UKI agentos_<version>.efi, which matches
# - systemd-boot-unsigned the bootloader # the MatchPattern= of mkosi.extra/usr/lib/sysupdate.d/20-uki.transfer.
# - util-linux, shadow-utils console login, setup, newuidmap for rootless podman # - KernelCommandLine:
# - systemd-pam login sessions (pam_systemd): Claude's user manager and its # - rw has the initrd mount the root filesystem writable. It finds it by its
# D-Bus, which rootless podman needs # partition type (mkosi.extra/usr/lib/repart.d/50-root.conf).
# - openssh-server ssh login for the user (keys only) # - The image policy only accepts an encrypted root filesystem (or none, at
# - zram-generator-defaults compressed swap in RAM # first boot) and a verity-checked /usr. Otherwise someone with the disk
# - podman, podman-docker containers, for all of Claude's toolchains (also as docker) # could swap in a plain root filesystem. Our UKI would boot it, and their
# - claude-code Claude Code (mkosi.sandbox/etc/yum.repos.d) # code could unseal the key of the real one.
# - git-core, openssh-clients Claude Code uses git; it pushes over ssh # - The root btrfs keeps one copy of its metadata instead of two (DUP,
# - the rest basic command-line tools Claude uses on the host # mkfs.btrfs's default). On a VM disk a second copy adds little.
# - The mount rate limit is raised from 5, which holds back mounts at boot
# and delays / and /usr by up to a second each.
# - KernelInitrdModules are what the initrd needs to find the disks of a VM,
# mount /usr and unlock the root filesystem. The kernel has virtio_blk,
# sd_mod, the TPM drivers and btrfs built in.
# - KernelModules keeps all modules but the hardware drivers, then adds back
# the drivers a VM needs (disks, network, screen) and those of podman's
# networks (veth, tun). The last matching line wins. Keyboard, USB and a
# basic screen are built into the kernel.
# - RemoveFiles drops System.map, which is only for debugging the kernel, and
# the udev hwdb, which holds hardware names and quirks a VM doesn't need.
# Without hwdb.d, systemd-hwdb-update can't build it again at boot.
Hostname=agentos-????
WithDocs=no
Packages= Packages=
kernel-core kernel-core # Unlike kernel, this has no extra drivers.
systemd systemd # The init and service manager is PID 1.
dbus-broker dbus-broker # D-Bus serves the user manager and podman.
systemd-udev systemd-udev # Udev, sysupdate, repart, cryptsetup are here.
systemd-networkd systemd-networkd # DHCP runs on every network card.
systemd-resolved systemd-resolved # DNS names are resolved here.
systemd-container systemd-container # Sysupdate needs its systemd-pull and gnupg2.
gnupg2 systemd-boot-unsigned # mkosi signs this boot loader.
systemd-boot-unsigned util-linux # The console login needs its login.
util-linux shadow-utils # Rootless podman needs its newuidmap.
shadow-utils systemd-pam # Logins get a session and user manager.
systemd-pam openssh-server # You can log in with ssh once there is a key.
openssh-server zram-generator-defaults # Swap is compressed in RAM.
zram-generator-defaults podman # Claude runs its tools in containers.
podman claude-code # Its repo is mkosi.sandbox/etc/yum.repos.d.
podman-docker git-core # Git pushes over ssh.
claude-code
git-core
openssh-clients
curl curl
tar tar
gzip gzip
@@ -59,38 +78,19 @@ Packages=
findutils findutils
procps-ng procps-ng
iproute iproute
WithDocs=no
Locale=C.UTF-8
# The UKI's file name in the ESP, as systemd-sysupdate names the ones it installs.
UnifiedKernelImageFormat=%i_%v UnifiedKernelImageFormat=%i_%v
# The console on screen and serial port, the machine ID from the VM's firmware
# (mkosi.extra/etc/machine-id is empty, so no boot counts as the first), no systemd-firstboot
# questions (agent-setup asks its own), freeing memory unused for an hour (damon_reclaim, in µs; the
# watermarks make it run whatever memory is free), so the host can take it back (virtio-balloon
# free page reporting).
KernelCommandLine= KernelCommandLine=
console=tty0
console=ttyS0,115200n8
quiet quiet
systemd.machine_id=firmware rw
systemd.firstboot=no systemd.image_policy=root=encrypted+absent:usr=verity:esp=unprotected
damon_reclaim.enabled=Y systemd.setenv=SYSTEMD_REPART_MKFS_OPTIONS_BTRFS=--metadata=single
damon_reclaim.min_age=3600000000 SYSTEMD_DEFAULT_MOUNT_RATE_LIMIT_BURST=50
damon_reclaim.wmarks_high=1000
damon_reclaim.wmarks_mid=999
damon_reclaim.wmarks_low=0
# Kernel modules in the initrd: only what finds and mounts the disks of a VM.
KernelInitrdModules= KernelInitrdModules=
virtio_blk
virtio_scsi virtio_scsi
sd_mod
nvme nvme
dm-verity dm-verity
dm-crypt
erofs erofs
ext4
# Kernel modules in the image: all but the hardware drivers, then the drivers of a VM (disks,
# network, screen) and of rootless podman's networks (pasta). The last matching line wins.
# Keyboard, USB and a basic screen are built into the kernel.
KernelModules= KernelModules=
/* /*
-/drivers/* -/drivers/*
@@ -99,31 +99,29 @@ KernelModules=
/drivers/md/* /drivers/md/*
nvme nvme
virtio_scsi virtio_scsi
sd_mod
virtio_net virtio_net
qemu_fw_cfg qemu_fw_cfg
bochs bochs
virtio-gpu virtio-gpu
veth veth
tun tun
# - System.map only for debugging the kernel
# - udev hwdb hardware names and quirks, nothing a VM needs
# - homed, userdbd, nsresourced unused services
# - sshd-keygen sshd uses one host key, kept on /var (sshd_config.d)
RemoveFiles= RemoveFiles=
/usr/lib/modules/*/System.map /usr/lib/modules/*/System.map
/usr/lib/udev/hwdb.bin /usr/lib/udev/hwdb.bin
/usr/lib/udev/hwdb.d /usr/lib/udev/hwdb.d
/usr/lib/systemd/system/systemd-homed*
/usr/lib/systemd/system/systemd-userdbd.*
/usr/lib/systemd/system/systemd-nsresourced.*
/usr/lib/systemd/system/sshd-keygen*
[Validation] [Validation]
# Signs systemd-boot and the UKI for Secure Boot, and puts our keys on the ESP, where systemd-boot # Validation signs the boot chain with mkosi.key, so the TPM unlocks the root
# enrolls them at first boot if the firmware is in setup mode (no keys enrolled; in Proxmox, an EFI # filesystem only for our UKIs.
# disk without pre-enrolled keys). mkosi.crt is the certificate; mkosi.key, its private key, is the
# SECUREBOOT_KEY secret of this repository, which the os workflow writes to mkosi.key.
SecureBoot=yes SecureBoot=yes
SecureBootKey=mkosi.key SignExpectedPcr=yes
SecureBootCertificate=mkosi.crt
[Runtime]
# Runtime sets up the test VM of mkosi vm. Each run boots a fresh copy, with
# root password root and no first boot questions.
Ephemeral=yes
CPUs=4
RAM=4G
RuntimeSize=40G
Credentials=passwd.plaintext-password.root=root
KernelCommandLineExtra=systemd.firstboot=no
+12 -11
View File
@@ -1,14 +1,15 @@
# This machine # This machine
You run on a small Fedora VM made for you, as the user `claude`, without root. A small Fedora VM, made for running Claude Code.
- **The OS is read-only**: you can't install anything on it. Run toolchains, languages and - Claude runs as the user `agent`, without root or sudo.
services in containers, with rootless `podman` (also as `docker`). For quick commands: - The OS is read-only. Packages can't be installed on it.
`podman run --rm -v "$PWD:/w" -w /w docker.io/library/python:3 python script.py`. - Run toolchains, languages and services in containers with rootless `podman`.
For longer work, keep a dev container you can install into: - For longer work, keep one container per worktree, named after its directory:
`podman run -d --name dev -v ~:/w -w /w quay.io/fedora/fedora:45 sleep infinity`, then - Start: `podman run -d --name "${PWD##*/}" -v "$PWD:$PWD" -w "$PWD" quay.io/fedora/fedora:latest sleep infinity`
`podman exec dev dnf install -y gcc` and `podman exec dev make`. - Install: `podman exec "${PWD##*/}" dnf install -y gcc`
- On the host: git, ssh, curl, tar/gzip/xz/zstd, find, diff, ps, ip. - Run: `podman exec "${PWD##*/}" make`
- **Everything resets at reboot**: your home (/var/home/claude), /tmp and all containers and - Remove: `podman rm -f "${PWD##*/}"`
images. Only your Claude login survives. Keep results somewhere else (push them to git, for - On the host: git, ssh, curl, tar, gzip, xz, zstd, find, diff, ps, ip.
example). The VM may reboot at about 04:10 to update. - The home directory (/home/agent), containers and images survive reboots.
- /tmp is wiped at every boot.
@@ -1,4 +1,5 @@
{ {
"permissions": { "defaultMode": "bypassPermissions" }, "permissions": { "defaultMode": "bypassPermissions" },
"skipDangerousModePermissionPrompt": true "skipDangerousModePermissionPrompt": true,
"remoteControlAtStartup": true
} }
-2
View File
@@ -1,2 +0,0 @@
# Claude's config, with its login, lives on /var/lib/agent (kept across reboots), not in the home.
CLAUDE_CONFIG_DIR=/var/lib/agent/claude
-2
View File
@@ -1,2 +0,0 @@
# /var, the only partition on disk that is written (mkosi.repart/30-var.conf). Grows to fill its partition at boot.
PARTLABEL=var /var ext4 x-systemd.growfs 0 2
View File
Whitespace-only changes.
@@ -1,9 +0,0 @@
# ssh: only the user claude, only with the key asked at setup. The host key is kept on /var
# (agent-boot makes it), so it stays the same across reboots. First value wins: this file sorts
# before Fedora's 50-redhat.conf.
HostKey /var/lib/agent/ssh_host_ed25519_key
AuthorizedKeysFile /var/lib/agent/authorized_keys
AllowUsers claude
PermitRootLogin no
PasswordAuthentication no
KbdInteractiveAuthentication no
+1 -1
View File
@@ -1 +1 @@
claude:524288:65536 agent:524288:65536
+1 -1
View File
@@ -1 +1 @@
claude:524288:65536 agent:524288:65536
+10
View File
@@ -0,0 +1,10 @@
# 50-root.conf makes the root filesystem at first boot, in the free space after
# /usr, and grows it with the disk. It holds all state: /etc and /var.
#
# The key is in the TPM, sealed to the signed PCR 11 policy of our UKIs
# (SignExpectedPcr= in mkosi.conf).
[Partition]
Type=root
Format=btrfs
Encrypt=tpm2
FactoryReset=yes
-4
View File
@@ -1,4 +0,0 @@
# Grow the /var partition to fill the disk at boot (systemd-repart); x-systemd.growfs in /etc/fstab
# then grows its filesystem.
[Partition]
Type=var
+2 -2
View File
@@ -1,3 +1,3 @@
# Containers (file watchers, systemd in containers) run out of Fedora's 128 inotify instances # 50-agent.conf raises the inotify instances per user from the kernel's 128,
# per user; 8192 is common on Kubernetes nodes. # which many containers running systemd can use up.
fs.inotify.max_user_instances = 8192 fs.inotify.max_user_instances = 8192
@@ -1,11 +1,8 @@
# DHCP on the real network cards. Kind=!* skips virtual links. # 80-dhcp.network turns on DHCP on the real network cards. Kind=!* skips
# virtual links such as those of containers.
[Match] [Match]
Type=ether Type=ether
Kind=!* Kind=!*
[Network] [Network]
DHCP=yes DHCP=yes
[DHCPv4]
# The hostname is the one asked at setup (agent-boot), not the DHCP server's.
UseHostname=no
@@ -1,18 +1,27 @@
# Services enabled in the image (mkosi runs systemctl preset-all). Fedora disables getty@.service, the # 50-agent.preset enables the services of the image. PID 1 applies it at first
# login on the screen (tty1, and tty2-6 through its autovt@ alias); this file sorts first, so it wins. # boot, so a change reaches existing machines only after a factory reset. It
# sorts before Fedora's presets, so it wins where they disagree.
# systemd-networkd is disabled by Fedora, which uses NetworkManager.
enable systemd-networkd.service enable systemd-networkd.service
enable systemd-resolved.service
enable sshd.service # preset-global.service applies the user presets.
enable preset-global.service
# sshd.path starts sshd once there is an ssh key.
enable sshd.path
disable sshd.service
# getty@.service is the login on the screen, which Fedora disables.
enable getty@.service enable getty@.service
enable agent-setup@.service tty1 ttyS0
enable etc-shadow.mount
enable agent-boot.service
enable claude-remote.path
enable systemd-sysupdate-update.timer enable systemd-sysupdate-update.timer
enable systemd-sysupdate-reboot.timer enable systemd-sysupdate-reboot.timer
# Fedora enables these, but they do nothing here: no PAM or crypto changes on a read-only /etc,
# no system or config extensions. # authselect-apply-changes fails, because /etc/authselect is on read-only /usr.
disable authselect-apply-changes.service disable authselect-apply-changes.service
disable fips-crypto-policy-overlay.service
disable systemd-sysext.service # systemd-homed, systemd-userdbd and systemd-nsresourced are unused here.
disable systemd-confext.service disable systemd-homed.service
disable systemd-homed-activate.service
disable systemd-userdbd.socket
disable systemd-nsresourced.socket
@@ -1,15 +0,0 @@
# Applies the setup answers at every boot (see /usr/libexec/agent-boot). Before the setup is done
# there are none; agent-setup starts this when it is.
[Unit]
Description=Apply agent setup
ConditionPathExists=/var/lib/agent/hostname
After=systemd-tmpfiles-setup.service
Before=sshd.service claude-remote.service
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/libexec/agent-boot
[Install]
WantedBy=multi-user.target
@@ -1,21 +0,0 @@
# First boot: asks for the root password, hostname and ssh key, on the screen (tty1) and the serial
# console (ttyS0) at once; whichever is answered first stops the other.
[Unit]
Description=Agent first-boot setup on %I
ConditionPathExists=!/var/lib/agent/hostname
After=systemd-tmpfiles-setup.service
Before=getty@%i.service serial-getty@%i.service
[Service]
Type=oneshot
ExecStart=/usr/libexec/agent-setup
StandardInput=tty
StandardOutput=tty
TTYPath=/dev/%I
TTYReset=yes
TTYVHangup=yes
# Answering on one console stops the setup on the other (SIGTERM), which is no failure.
SuccessExitStatus=SIGTERM
[Install]
WantedBy=multi-user.target
@@ -1,9 +0,0 @@
# Starts Claude (Remote Control) once it is logged in: at boot, or when the user first logs in.
[Unit]
Description=Start Claude Remote Control once logged in
[Path]
PathExists=/var/lib/agent/claude/.credentials.json
[Install]
WantedBy=multi-user.target
@@ -1,14 +0,0 @@
# Claude Code, in the background, controlled from claude.ai/code or the Claude app (Remote Control).
# Works in Claude's home. Started by claude-remote.path once Claude is logged in.
[Unit]
Description=Claude Code Remote Control
Wants=network-online.target user@1000.service
After=network-online.target user@1000.service agent-boot.service
[Service]
User=claude
WorkingDirectory=~
Environment=CLAUDE_CONFIG_DIR=/var/lib/agent/claude XDG_RUNTIME_DIR=/run/user/1000
ExecStart=/usr/bin/claude remote-control --name %H
Restart=always
RestartSec=10s
@@ -1,14 +0,0 @@
# The root password. /etc is read-only, so agent-setup writes the shadow file to /var and this
# mounts it over /etc/shadow.
[Unit]
Description=Root password from /var
ConditionPathExists=/var/lib/agent/etc/shadow
RequiresMountsFor=/var
[Mount]
What=/var/lib/agent/etc/shadow
Where=/etc/shadow
Options=bind
[Install]
WantedBy=local-fs.target
@@ -0,0 +1,20 @@
# preset-global.service applies the user presets at first boot, as PID 1 does
# for the system presets. It runs before basic.target, so before any user
# manager starts, which needs DefaultDependencies=no. It is the same as
# ParticleOS's. systemd 263 can apply presets at build time instead, with
# systemctl preset-all --vendor.
[Unit]
Description=Apply the user presets
ConditionFirstBoot=yes
DefaultDependencies=no
Before=basic.target
Conflicts=shutdown.target
Before=shutdown.target
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=systemctl preset-all --global
[Install]
WantedBy=basic.target
@@ -0,0 +1,11 @@
# sshd.path starts sshd only once root or the user agent has an ssh key, so a
# new VM has no open port.
[Unit]
Description=Start sshd once an ssh key is set
[Path]
PathExists=/home/agent/.ssh/authorized_keys
PathExists=/root/.ssh/authorized_keys
[Install]
WantedBy=multi-user.target
@@ -1,4 +0,0 @@
# The host key is made by agent-boot, once the setup is done; agent-setup then starts sshd.
[Unit]
After=agent-boot.service
ConditionPathExists=/var/lib/agent/ssh_host_ed25519_key
@@ -0,0 +1,3 @@
# 50-agent.preset enables the user services of the image.
# preset-global.service applies it at first boot.
enable claude-remote.path
@@ -0,0 +1,13 @@
# claude-remote.path starts claude-remote.service once Claude is logged in.
# It runs in the user manager of agent, which linger starts at boot
# (mkosi.extra/usr/lib/tmpfiles.d/agent.conf). ConditionUser keeps it out of
# the user manager of root.
[Unit]
Description=Start Claude Remote Control once logged in
ConditionUser=agent
[Path]
PathExists=%h/.claude/.credentials.json
[Install]
WantedBy=default.target
@@ -0,0 +1,18 @@
# claude-remote.service runs Claude Code in the background, in ~/work of the
# user agent, so it can be used from claude.ai/code or the Claude app. Claude
# never saves trust for a home directory, so it can't run in ~ itself.
# claude-remote.path starts it once Claude is logged in. The user manager can't
# wait for the network, so Restart= retries until it is up.
#
# Remote Control redraws its status screen on stdout every second, which would
# flood the journal. Its errors go to stderr, which the journal keeps.
[Unit]
Description=Claude Code Remote Control
[Service]
WorkingDirectory=%h/work
ExecStart=/usr/bin/claude remote-control --name %H
StandardOutput=null
StandardError=journal
Restart=always
RestartSec=10s
@@ -1,19 +0,0 @@
# Updates the root filesystem: writes the next version to the unused root partition.
# Verify=yes: SHA256SUMS.gpg must be signed by a key in /usr/lib/systemd/import-pubring.pgp, and
# SHA256SUMS checks each download.
[Transfer]
ProtectVersion=%A
Verify=yes
[Source]
Type=url-file
Path=https://git.plabble.org/api/packages/Job79/generic/agent/latest/
MatchPattern=agent_@v.root-%a.@u.raw.zst
[Target]
Type=partition
Path=auto
MatchPattern=agent_@v
MatchPartitionType=root
PartitionFlags=0
ReadOnly=1
@@ -0,0 +1,20 @@
# 10-usr.transfer writes the next version of /usr to the inactive /usr
# partition.
#
# systemd-sysupdate requires SHA256SUMS.gpg to be signed by a key in
# /usr/lib/systemd/import-pubring.pgp, and SHA256SUMS checks each download.
[Transfer]
ProtectVersion=%A
[Source]
Type=url-file
Path=https://git.plabble.org/api/packages/Job79/generic/agentos/latest/
MatchPattern=agentos_@v.usr-%a.@u.raw.zst
[Target]
Type=partition
Path=auto
MatchPattern=agentos_@v
MatchPartitionType=usr
PartitionFlags=0
ReadOnly=1
@@ -1,17 +0,0 @@
# Updates the root filesystem's dm-verity hashes, next to 10-root.transfer (see it for Verify=yes).
[Transfer]
ProtectVersion=%A
Verify=yes
[Source]
Type=url-file
Path=https://git.plabble.org/api/packages/Job79/generic/agent/latest/
MatchPattern=agent_@v.root-%a-verity.@u.raw.zst
[Target]
Type=partition
Path=auto
MatchPattern=agent_@v_verity
MatchPartitionType=root-verity
PartitionFlags=0
ReadOnly=1
@@ -0,0 +1,17 @@
# 11-usr-verity.transfer writes the dm-verity hashes that go with
# 10-usr.transfer, which explains how downloads are checked.
[Transfer]
ProtectVersion=%A
[Source]
Type=url-file
Path=https://git.plabble.org/api/packages/Job79/generic/agentos/latest/
MatchPattern=agentos_@v.usr-%a-verity.@u.raw.zst
[Target]
Type=partition
Path=auto
MatchPattern=agentos_@v_verity
MatchPartitionType=usr-verity
PartitionFlags=0
ReadOnly=1
@@ -1,22 +1,23 @@
# Installs the next UKI, which systemd-boot boots by default. Verify=yes: see 10-root.transfer. # 20-uki.transfer installs the next UKI, which systemd-boot then boots by
# It gets three tries (boot counting, the +@l-@d in its name; no Mode=0444, systemd-boot can't # default. For how downloads are checked, see 10-usr.transfer.
# rename a read-only file): systemd-bless-boot marks it good once a boot gets through #
# (boot-complete.target); if none does, systemd-boot goes back to the previous UKI, and with it # The new UKI gets three tries (boot counting: the +@l-@d in its name).
# the previous root partition (each UKI holds its root hash). # systemd-bless-boot marks it good once a boot reaches boot-complete.target.
# If no boot does, systemd-boot goes back to the previous UKI, and with it to
# the previous /usr partition, because each UKI holds its usr hash.
[Transfer] [Transfer]
ProtectVersion=%A ProtectVersion=%A
Verify=yes
[Source] [Source]
Type=url-file Type=url-file
Path=https://git.plabble.org/api/packages/Job79/generic/agent/latest/ Path=https://git.plabble.org/api/packages/Job79/generic/agentos/latest/
MatchPattern=agent_@v.efi MatchPattern=agentos_@v.efi
[Target] [Target]
Type=regular-file Type=regular-file
Path=/EFI/Linux Path=/EFI/Linux
PathRelativeTo=boot PathRelativeTo=boot
MatchPattern=agent_@v+@l-@d.efi agent_@v+@l.efi agent_@v.efi MatchPattern=agentos_@v+@l-@d.efi agentos_@v+@l.efi agentos_@v.efi
TriesLeft=3 TriesLeft=3
TriesDone=0 TriesDone=0
InstancesMax=2 InstancesMax=2
@@ -0,0 +1,3 @@
# agent.conf adds the user agent, which Claude runs as. /etc/subuid and
# /etc/subgid give it the ids that rootless podman needs.
u agent 1000 "Agent" /home/agent /bin/bash
@@ -1,2 +0,0 @@
# The user Claude runs as; /etc/subuid and /etc/subgid give it the ids of rootless podman.
u claude 1000 "Claude" /var/home/claude /bin/bash
+13 -10
View File
@@ -1,10 +1,13 @@
# State kept across reboots: the setup answers, the ssh host key and Claude's login # agent.conf makes the home of the user agent, and in it work, where
# (agent-boot wipes the rest of Claude's config). # claude-remote.service runs (mkosi.extra/usr/lib/systemd/user).
d /var/lib/agent 0755 root root - d /home/agent 0700 agent agent
d /var/lib/agent/claude 0700 claude claude - d /home/agent/work 0700 agent agent
# Wiped at every boot (D empties a directory at boot): Claude's home, with its podman storage, and
# temporary files. These, /tmp and Claude's config are all that Claude can write. # .claude.json trusts ~/work, so claude-remote.service can run there without
D /var/home/claude 0700 claude claude - # the trust dialog first. It is only made if missing, because Claude keeps its
D /var/tmp 1777 root root - # login there too.
# Start Claude's user manager at boot, for rootless podman and its own services. f /home/agent/.claude.json 0600 agent agent - {"projects":{"/home/agent/work":{"hasTrustDialogAccepted":true}}}
f /var/lib/systemd/linger/claude
# linger starts the user manager of agent at boot, for rootless podman and
# claude-remote.path.
f /var/lib/systemd/linger/agent
@@ -0,0 +1,44 @@
# factory-etc.conf links what the image needs from /usr/share/factory/etc
# (mkosi.finalize) into the empty /etc at boot, so updates to /usr take effect
# in /etc too. The rest of the factory is unused package config. /etc itself
# holds what the machine writes: passwd, shadow, group, machine-id, ld.so.cache,
# /etc/systemd and the ssh host keys. systemd's own etc.conf sets up
# os-release, nsswitch.conf and pam.d.
#
# /etc/systemd is filled from the presets at first boot: by PID 1 for system
# units, and by mkosi.extra/usr/lib/systemd/system/preset-global.service for
# user units.
#
# subuid and subgid are copied, because shadow-utils won't read them through a
# link. Rootless podman needs them.
C /etc/subgid
C /etc/subuid
# /etc/ssh is a writable directory, because sshd-keygen writes the host keys
# there at first boot.
d /etc/ssh 0755
L /etc/ssh/moduli
L /etc/ssh/ssh_config
L /etc/ssh/ssh_config.d
L /etc/ssh/sshd_config
L /etc/ssh/sshd_config.d
# authselect holds the PAM files that /etc/pam.d links to.
L /etc/authselect
L /etc/security
L /etc/environment
L /etc/login.defs
L /etc/shells
# pki and ssl hold the CA certificates, and crypto-policies the TLS and ssh
# settings.
L /etc/pki
L /etc/ssl
L /etc/crypto-policies
L /etc/bashrc
L /etc/profile
L /etc/profile.d
L /etc/protocols
L /etc/services
L /etc/hostname
L /etc/claude-code
-9
View File
@@ -1,9 +0,0 @@
#!/bin/bash
# Every boot (agent-boot.service), and after the setup: sets the hostname asked at setup (/etc is
# read-only, so it is set on every boot), makes the ssh host key the first time, and wipes
# Claude's config except its login, so Claude starts fresh but logged in.
set -euo pipefail
cd /var/lib/agent
hostnamectl hostname --transient "$(cat hostname)"
[[ -f ssh_host_ed25519_key ]] || ssh-keygen -q -t ed25519 -N '' -f ssh_host_ed25519_key
find claude -mindepth 1 -maxdepth 1 ! -name .credentials.json ! -name .claude.json -exec rm -rf {} +
-29
View File
@@ -1,29 +0,0 @@
#!/bin/bash
# First boot: asks for the root password, the hostname and the ssh key of the user claude, on the
# screen (tty1) and the serial console (ttyS0) at once (agent-setup@.service).
# /etc is read-only, so the answers go to /var/lib/agent: the password to a shadow file there
# (etc-shadow.mount puts it over /etc/shadow), the rest is applied by agent-boot at every boot.
set -euo pipefail
echo "== Agent setup =="
while :; do
read -rsp "Root password: " pw; echo
read -rsp "Again: " pw2; echo
[[ -n $pw && $pw == "$pw2" ]] && break
echo "Passwords do not match, try again."
done
install -d -m 0700 /var/lib/agent/etc
cp /etc/passwd /etc/shadow /var/lib/agent/etc/
echo "root:$pw" | chpasswd --prefix /var/lib/agent
systemctl start etc-shadow.mount
read -rp "Hostname [agent]: " name
read -rp "SSH public key for the user claude: " key
[[ -n $key ]] && install -m 0644 /dev/stdin /var/lib/agent/authorized_keys <<<"$key"
# Written last: its presence marks the setup as done.
echo "${name:-agent}" > /var/lib/agent/hostname
systemctl start agent-boot.service sshd.service
echo "Done. Log in with ssh claude@<this VM>, run claude and log in with your account."
echo "Remote Control then starts by itself."
# Stop the setup on the other console, which then shows its login.
systemctl --no-block stop "agent-setup@*.service"
Executable
+8
View File
@@ -0,0 +1,8 @@
#!/bin/bash
# mkosi.finalize keeps the /etc that the packages and mkosi.extra/etc made in
# /usr/share/factory/etc, because the image ships only /usr. At boot,
# mkosi.extra/usr/lib/tmpfiles.d/factory-etc.conf links from it what /etc needs.
set -euo pipefail
cp -a --no-target-directory --update=none "$BUILDROOT/etc" \
"$BUILDROOT/usr/share/factory/etc"
+2 -1
View File
@@ -1,4 +1,5 @@
# EFI system partition: systemd-boot and the UKIs (two versions at most). # 00-esp.conf defines the EFI system partition. It holds systemd-boot and the
# UKIs, two versions at most.
[Partition] [Partition]
Type=esp Type=esp
Format=vfat Format=vfat
-15
View File
@@ -1,15 +0,0 @@
# The root filesystem, slot A: /etc and /usr, read-only erofs protected by dm-verity (roothash= in
# the UKI). Updates replace it whole. /var, the state, is its own partition (30-var.conf).
[Partition]
Type=root
Label=%M_%A
Format=erofs
Compression=zstd
CopyFiles=/
ExcludeFilesTarget=/var/
Verity=data
VerityMatchKey=root
SizeMinBytes=1G
SizeMaxBytes=1G
# The file name holds the partition UUID, which roothash= finds the root by; updates keep it (@u in sysupdate.d).
SplitName=%t.%U
+17
View File
@@ -0,0 +1,17 @@
# 10-usr.conf defines /usr in slot A: the OS as read-only erofs, protected by
# dm-verity (usrhash= in the UKI). Updates replace it whole. The image holds
# nothing else but the ESP: the initrd makes the root filesystem, with /etc
# and /var, at first boot (mkosi.extra/usr/lib/repart.d/50-root.conf).
[Partition]
Type=usr
Label=%M_%A
Format=erofs
Compression=lz4hc
CopyFiles=/usr:/
Verity=data
VerityMatchKey=usr
SizeMinBytes=1G
SizeMaxBytes=1G
# SplitName holds the partition UUID (%U): usrhash= finds /usr by it, and
# updates keep it (@u in mkosi.extra/usr/lib/sysupdate.d).
SplitName=%t.%U
-9
View File
@@ -1,9 +0,0 @@
# dm-verity hashes of the root filesystem, slot A.
[Partition]
Type=root-verity
Label=%M_%A_verity
Verity=hash
VerityMatchKey=root
SizeMinBytes=64M
SizeMaxBytes=64M
SplitName=%t.%U
+9
View File
@@ -0,0 +1,9 @@
# 11-usr-verity.conf holds the dm-verity hashes of /usr in 10-usr.conf.
[Partition]
Type=usr-verity
Label=%M_%A_verity
Verity=hash
VerityMatchKey=usr
SizeMinBytes=16M
SizeMaxBytes=16M
SplitName=%t.%U
-7
View File
@@ -1,7 +0,0 @@
# The root filesystem, slot B: empty until systemd-sysupdate writes the next version.
[Partition]
Type=root
Label=_empty
SizeMinBytes=1G
SizeMaxBytes=1G
SplitName=-
+8
View File
@@ -0,0 +1,8 @@
# 20-usr-b.conf defines /usr in slot B. It stays empty until systemd-sysupdate
# writes the next version to it.
[Partition]
Type=usr
Label=_empty
SizeMinBytes=1G
SizeMaxBytes=1G
SplitName=-
-7
View File
@@ -1,7 +0,0 @@
# dm-verity hashes of the root filesystem, slot B.
[Partition]
Type=root-verity
Label=_empty
SizeMinBytes=64M
SizeMaxBytes=64M
SplitName=-
+8
View File
@@ -0,0 +1,8 @@
# 21-usr-verity-b.conf holds the dm-verity hashes for 20-usr-b.conf, empty
# until the next update.
[Partition]
Type=usr-verity
Label=_empty
SizeMinBytes=16M
SizeMaxBytes=16M
SplitName=-
-10
View File
@@ -1,10 +0,0 @@
# /var: Claude's home and the state that reboots and updates keep (/var/lib/agent: the setup answers
# and Claude's login, the root password). Mounted by /etc/fstab, which also grows it to fill the
# disk at boot. Claude's home, with its containers, is wiped at every boot (tmpfiles.d/agent.conf).
[Partition]
Type=var
Label=var
Format=ext4
CopyFiles=/var:/
Minimize=guess
SplitName=-
@@ -1,7 +1,5 @@
# Claude Code # claude-code.repo adds Anthropic's package repository, stable channel. mkosi
# # uses it to install the claude-code package (mkosi.conf).
# Anthropic's package repository, stable channel. The key's fingerprint is
# 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE.
[claude-code] [claude-code]
name=Claude Code name=Claude Code
baseurl=https://downloads.claude.ai/claude-code/rpm/stable baseurl=https://downloads.claude.ai/claude-code/rpm/stable
+8 -5
View File
@@ -1,5 +1,8 @@
#!/bin/sh #!/bin/bash
# Image version # mkosi.version prints the build time in UTC (YYYYMMDDhhmm) and the git
# # commit. Every build gets a higher version than the one before, which is how
# The build time (UTC), so every build is newer than the last. # systemd-sysupdate tells that an update is newer. The commit tells which
date -u +%Y%m%d%H%M # source an image was built from.
set -euo pipefail
commit=$(git rev-parse --short HEAD)
echo "$(date -u +%Y%m%d%H%M).$commit"