feat: unattended setup from credentials, rewrite README

agent-setup takes its answers from the credentials agent.password,
agent.hostname and agent.ssh-key when they are given, so a test VM boots
without typing. The README is shorter, explains the mkosi layout and
shows how to boot a test VM with these credentials. Also uploads the
manifest in the os workflow and ignores the test VM files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Job79andClaude Opus 5.5 committed 2026-11-16 21:02:29 +01:00
1 parent 3ae080f978
commit ce1faca070
6 files changed
+47 -32

No files matched your search

+1 -1
View File
@@ -53,6 +53,6 @@ jobs:
working-directory: mkosi.output working-directory: mkosi.output
run: | run: |
curl -fsS -H "$AUTH" -X DELETE "$PKG" || true curl -fsS -H "$AUTH" -X DELETE "$PKG" || true
for f in agent_*.efi agent_*.root-*.raw.zst agent.qcow2 SHA256SUMS.gpg SHA256SUMS; do for f in agent_*.efi agent_*.root-*.raw.zst agent.qcow2 agent_*.manifest SHA256SUMS.gpg SHA256SUMS; do
curl -fsS -o /dev/null -H "$AUTH" --upload-file "$f" "$PKG/$f" curl -fsS -o /dev/null -H "$AUTH" --upload-file "$f" "$PKG/$f"
done done
+2 -3
View File
@@ -1,5 +1,4 @@
# Ignored files
#
# Build output, and the Secure Boot private key (mkosi.conf, [Validation]).
mkosi.output/ mkosi.output/
mkosi.key mkosi.key
test.qcow2
vars.fd
+17 -17
View File
@@ -1,42 +1,42 @@
# agent-mkosi # 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. 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.
- **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`). - **Resets at reboot:** 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. - **Read-only OS:** the root filesystem is read-only, so Claude can't change the OS. All state lives on `/var`.
- **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. - **Tools in containers:** Claude runs as the user `claude`, without root, and runs its toolchains in containers with podman. The host has only git, ssh and basic command-line tools.
- **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. - **Self-updating:** the `os` rebuilds weekly and updates with systemd-sysupdate.
- **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 ## 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`. 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 in Secure Boot setup mode. The console asks for a root password, a hostname and an ssh public key for the user `claude`.
Then log Claude in once: Then log Claude in once:
```sh ```sh
ssh claude@<vm> ssh claude@<vm>
claude # trust the folder (your home), then /login with your Claude account claude # trust the folder, 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`. The VM then shows up in claude.ai/code and the Claude app under its hostname.
## Development ## 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). When changing files, follow [STYLE.md](STYLE.md).
```sh ```sh
mkosi genkey # local test only, CI uses the SECUREBOOT_KEY secret
mkosi build 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 make up an update. To boot it with Secure Boot (needs `qemu-kvm-core edk2-ovmf`):
`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 ```sh
qemu-img convert -O qcow2 mkosi.output/agent_<version>.raw test.qcow2 && qemu-img resize test.qcow2 40G qemu-img create -f qcow2 -F raw -b $PWD/mkosi.output/agent_<version>.raw test.qcow2 40G
cp /usr/share/edk2/ovmf/OVMF_VARS.fd vars.fd 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 \ qemu-kvm -m 8G -cpu host -nographic -nic user,model=virtio-net-pci,hostfwd=tcp::2222-:22 -drive file=test.qcow2,if=virtio \
-machine q35,smm=on -global driver=cfi.pflash01,property=secure,value=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 -drive if=pflash,format=raw,readonly=on,file=/usr/share/edk2/ovmf/OVMF_CODE.secboot.fd -drive if=pflash,format=raw,file=vars.fd \
-smbios type=11,value=io.systemd.credential:agent.password=test \
-smbios type=11,value=io.systemd.credential.binary:agent.ssh-key=$(base64 -w0 ~/.ssh/id_ed25519.pub)
``` ```
The credentials answer the setup, so it boots straight to a login (root, password `test`) on the serial console. Ctrl-a x quits. Then `ssh -p 2222 claude@localhost`.
+3 -1
View File
@@ -14,8 +14,10 @@ Release=45
Format=disk Format=disk
ImageId=agent ImageId=agent
OutputDirectory=mkosi.output OutputDirectory=mkosi.output
# The UKI and root partitions are published as updates (systemd-sysupdate).
SplitArtifacts=uki,partitions SplitArtifacts=uki,partitions
# Lists the packages and versions in the image, to tell which builds a CVE
# affects. .gitea/workflows/os.yml publishes it with the image.
ManifestFormat=json
[Content] [Content]
Bootable=yes Bootable=yes
@@ -11,6 +11,7 @@ Before=getty@%i.service serial-getty@%i.service
[Service] [Service]
Type=oneshot Type=oneshot
ImportCredential=agent.*
ExecStart=/usr/libexec/agent-setup ExecStart=/usr/libexec/agent-setup
StandardInput=tty StandardInput=tty
StandardOutput=tty StandardOutput=tty
+23 -10
View File
@@ -6,22 +6,35 @@
# /var/lib/agent. The password goes into a shadow file there, which # /var/lib/agent. The password goes into a shadow file there, which
# etc-shadow.mount puts over /etc/shadow. agent-boot applies the rest at every # etc-shadow.mount puts over /etc/shadow. agent-boot applies the rest at every
# boot. # boot.
#
# With the credential agent.password, it asks nothing and takes the answers
# from the credentials agent.password, agent.hostname and agent.ssh-key, such
# as for a test VM (README.md).
set -euo pipefail set -euo pipefail
echo "== Agent setup ==" cred() { cat "${CREDENTIALS_DIRECTORY:-/nonexistent}/agent.$1" 2>/dev/null; }
if pw=$(cred password); then
# Both consoles run this script. Only one may do the setup.
exec 9>/run/agent-setup.lock
flock -n 9 || exit 0
name=$(cred hostname) || true
key=$(cred ssh-key) || true
else
echo "== Agent setup =="
while :; do
read -rsp "Root password: " pw; echo
read -rsp "Again: " pw2; echo
[[ -n $pw && $pw == "$pw2" ]] && break
echo "Passwords do not match, try again."
done
read -rp "Hostname [agent]: " name
read -rp "SSH public key for the user claude: " key
fi
while :; do
read -rsp "Root password: " pw; echo
read -rsp "Again: " pw2; echo
[[ -n $pw && $pw == "$pw2" ]] && break
echo "Passwords do not match, try again."
done
install -d -m 0700 /var/lib/agent/etc install -d -m 0700 /var/lib/agent/etc
cp /etc/passwd /etc/shadow /var/lib/agent/etc/ cp /etc/passwd /etc/shadow /var/lib/agent/etc/
echo "root:$pw" | chpasswd --prefix /var/lib/agent echo "root:$pw" | chpasswd --prefix /var/lib/agent
systemctl start etc-shadow.mount systemctl start etc-shadow.mount
read -rp "Hostname [agent]: " name
read -rp "SSH public key for the user claude: " key
[[ -n $key ]] && install -m 0644 /dev/stdin /var/lib/agent/authorized_keys <<<"$key" [[ -n $key ]] && install -m 0644 /dev/stdin /var/lib/agent/authorized_keys <<<"$key"
# Written last: its presence marks the setup as done. # Written last: its presence marks the setup as done.
echo "${name:-agent}" > /var/lib/agent/hostname echo "${name:-agent}" > /var/lib/agent/hostname