Files
agent-mkosi/README.md
T
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

2.2 KiB

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, /tmp and 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 os rebuilds 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 with Secure Boot (needs qemu-kvm-core edk2-ovmf):

mkosi -f vm

The [Runtime] section of mkosi.conf answers the setup, so it boots straight to a login (root, password test). Then ssh -p 2222 claude@localhost with your own key (mkosi.credentials/agent.ssh-key).

mkosi vm needs systemd on the host. Without it, such as in a dev container, run mkosi in a container with systemd (Containerfile):

podman build -t mkosi-vm .
podman run -d --name mkosi --systemd=always --privileged --device /dev/kvm -v .:/repo -v ~/.ssh:/root/.ssh:ro -w /repo mkosi-vm
podman exec -it mkosi mkosi -f vm
podman exec -it mkosi ssh -p 2222 claude@localhost    # in another terminal