# agentos A VM that runs [Claude Code](https://claude.com/claude-code) in the background. It is a minimal Fedora image built with [mkosi](https://github.com/systemd/mkosi). You control Claude from claude.ai/code or the Claude app (Remote Control), or log in with ssh. - **Read-only OS:** `/usr` is read-only, so Claude can't change the OS. Secure Boot verifies the UKI (kernel, initrd and command line), which holds the dm-verity hash that verifies `/usr`. - **Encrypted with a TPM:** everything that isn't read-only, such as `/etc`, `/var` and `/home`, is encrypted. The TPM unlocks it only for correctly signed UKIs. - **Easy to reset:** a factory reset wipes everything that isn't read-only, and the VM sets itself up again as at first boot. - **Tools in containers:** Claude runs as the user `agent`, without root, and runs its toolchains in containers with podman. - **Self-updating:** the image rebuilds weekly. A bad update rolls back by itself. ## Install Download [the disk image](https://git.plabble.org/api/packages/Job79/generic/agentos/latest/agentos.qcow2), resize it to the disk size you want and boot it with UEFI and a TPM. At first boot, the screen offers a recovery key for the encrypted disk and asks for a root password. Then log in as root and put your ssh key in `/home/agent/.ssh/authorized_keys` (for root: `~/.ssh/authorized_keys`), which starts sshd. Run `claude` once as `agent` to sign in. The VM then shows up in claude.ai/code and the Claude app under its hostname: `agentos-` and four hex digits. To start over, run `systemctl start factory-reset.target` as root. It reboots and wipes the root partition (`/etc`, `/var` and `/home`), and the VM sets itself up as at first boot. ## Development `mkosi build` signs with `mkosi.key`, the private key of `mkosi.crt`, which only CI has (the `SECUREBOOT_KEY` secret). `mkosi genkey` won't replace `mkosi.crt`, so local builds sign with a test key. Make one: ```sh openssl req -new -x509 -newkey rsa:2048 -nodes -subj /CN=test \ -keyout ~/test.key -out ~/test.crt ``` and point `mkosi.local.conf` at it, which mkosi reads and git ignores: ```ini [Validation] SecureBootKey=~/test.key SecureBootCertificate=~/test.crt SignExpectedPcrKey=~/test.key SignExpectedPcrCertificate=~/test.crt VerityKey=~/test.key VerityCertificate=~/test.crt ``` Then run `mkosi build`. `mkosi.output/` then holds the disk image (`agentos_.raw`) and the UKI and /usr partitions that make up an update. To build and boot a test VM: ```sh mkosi -f vm # This opens the console. Log in as root, password root. mkosi ssh # This logs in as root with ssh, in another terminal. ```