Files
agentos/README.md
T
Job79andClaude Opus 5.5 5255656258
os / os (push) Canceled after 0s
refactor: style pass, tools tree and fixes from a test build
- Follow AGENTS.md style: headers start with the file's name, short
  notes are full sentences, comments within 80 columns.
- Build with mkosi's tools tree, pinned to the image's release
  (ToolsTreeRelease=%r): rawhide's repositories made the image rawhide.
- Incremental builds with mkosi.cache/ for faster local rebuilds.
- Hostname= instead of systemd.hostname= on the kernel command line.
- mkosi.finalize: bash, no cd, and L+ for /etc/systemd. PID 1 applies
  the presets at first boot and made /etc/systemd/system, which blocked
  the link, so /etc/systemd/user (the user's D-Bus) was missing.
- Disable homed, userdbd and nsresourced with presets instead of
  deleting their units. Drop modules the kernel has built in.
- mkosi.version adds the git commit to the version.
- One dev container per worktree or session in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 20:37:26 +01:00

52 lines
2.1 KiB
Markdown

# agent-mkosi
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/agent/latest/agent.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: `agent-` 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
```sh
mkosi genkey # This is for local tests. CI uses the SECUREBOOT_KEY secret.
mkosi build
```
`mkosi.output/` then holds the disk image (`agent_<version>.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.
```