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. A new version gets three tries to boot; if none gets through, systemd-boot goes back to the previous one.
  • 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.
  • 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.

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 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.

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.sandbox/ adds the Claude Code package repository).

mkosi build

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).

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):

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 \
  -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
S
Description
No description provided
Readme
41 KiB
0 Stars 1 Watchers 0 Forks