Files
agent-mkosi/README.md
T
2026-11-15 15:52:10 +01:00

3.2 KiB

agent-mkosi

A VM that runs Claude Code in the background, packaged as a minimal Fedora image built with mkosi. You control Claude from claude.ai/code, 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).
  • 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.
  • Self-updating: like 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.
  • 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.
  • Hardened: a firewall that drops all incoming traffic but ssh, KSPP sysctls and kernel arguments, and systemd-oomd kills Claude's work, not the system, when it runs the VM out of memory.

Install

Download the disk image (built by the os workflow), resize it to the disk size you want (/var grows to fill it) and boot it with UEFI. The screen and the serial console ask 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 (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

mkosi.conf defines the OS (mkosi.extra/ is copied to /, mkosi.repart/ is the disk layout, mkosi.prepare installs Claude Code).

mkosi build

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 (needs qemu-kvm-core edk2-ovmf; ssh on port 2222):

qemu-img convert -O qcow2 mkosi.output/agent_<version>.raw test.qcow2 && qemu-img resize test.qcow2 40G
cp /usr/share/edk2/ovmf/OVMF_VARS.fd vars.fd
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 \
  -drive if=pflash,format=raw,readonly=on,file=/usr/share/edk2/ovmf/OVMF_CODE.fd -drive if=pflash,format=raw,file=vars.fd