51272b708c9d9dcaefe4a34eaacd3ada4372750e
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.
- Resets at reboot: Claude's home,
/tmpand all containers are wiped at every boot. Only the setup answers and Claude's login survive (/var/lib/agent). - Read-only OS: the root filesystem is read-only, so Claude can't change the OS. All state lives on
/var. - Tools in containers: Claude runs as the user
claude, without root, and runs its toolchains in containers with podman. The host has only git, ssh and basic command-line tools. - Self-updating: the
osrebuilds weekly and updates with systemd-sysupdate.
Install
Download the disk image, resize it to the disk size you want and boot it with UEFI in Secure Boot setup mode. The console asks for a root password, a hostname and an ssh public key for the user claude.
Then log Claude in once:
ssh claude@<vm>
claude # trust the folder, then /login with your Claude account
The VM then shows up in claude.ai/code and the Claude app under its hostname.
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 root partitions that make up an update.
To build and boot a test VM (needs qemu-kvm-core edk2-ovmf):
mkosi -f vm # log in as root, password test
ssh -p 2222 claude@localhost # with your own key
AGENTS.md has the details, such as testing from a dev container.
Languages
Shell
100%