gitea-runner 6 has no builtin:checkout, and plain Fedora has no Node.js for actions/checkout, so the workflow fetches the commit with git. Setting permissions: keeps read access for that and asks for package writes. mkosi genkey won't replace mkosi.crt, so the docs now sign local builds with a test key in mkosi.local.conf, which also covers the PCR and verity keys. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
70 lines
2.6 KiB
Markdown
70 lines
2.6 KiB
Markdown
# 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_<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.
|
|
```
|