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>
agent-mkosi
A VM that runs Claude Code in the background. It is a minimal Fedora image built with mkosi. You control Claude from claude.ai/code or the Claude app (Remote Control), or log in with ssh.
- Read-only OS:
/usris read-only, so Claude can't change the OS. Secure Boot verifies the UKI (kernel, initrd and command line), which holds the dm-verity hash that verifies/usr. - Encrypted with a TPM: everything that isn't read-only, such as
/etc,/varand/home, is encrypted. The TPM unlocks it only for those signed UKIs. - 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
Download the disk image,
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: agent- and four hex
digits.
To start over, run systemctl start factory-reset.target as root. It reboots
and wipes /etc and /var, and the VM sets itself up as at first boot.
Development
mkosi genkey # local test only, CI uses the SECUREBOOT_KEY secret
mkosi build
mkosi.output/ then holds the disk image (agent_<version>.raw) and the UKI
and /usr partitions that make up an update.
To build and boot a test VM (needs qemu-kvm-core edk2-ovmf swtpm openssh-clients socat):
mkosi -f vm # opens its console: log in as root, password root
mkosi ssh # in another terminal: ssh in as root