Replace mkosi.prepare with Anthropic's rpm repository (mkosi.sandbox/), switch the workflow to the gitea context, and start STYLE.md with a consistent file header. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
43 lines
3.8 KiB
Markdown
43 lines
3.8 KiB
Markdown
# agent-mkosi
|
|
|
|
A VM that runs [Claude Code](https://claude.com/claude-code) in the background, packaged as a minimal Fedora image built with [mkosi](https://github.com/systemd/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](../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](https://git.plabble.org/api/packages/Job79/generic/agent/latest/agent.qcow2) (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:
|
|
|
|
```sh
|
|
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).
|
|
|
|
```sh
|
|
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):
|
|
|
|
```sh
|
|
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
|
|
```
|