feat: root adds the ssh keys, mkosi ssh for the test VM

The setup no longer asks for an ssh key. Root logs in on the console and
adds keys for claude and root to /var/lib/agent. Root may log in with
ssh, and its home is a tmpfs that is wiped at every boot. The test VM
uses mkosi ssh instead of a forwarded port, so the agent.ssh-key
credential is gone.

Also mount /var with noatime, move STYLE.md into AGENTS.md and rewrite
comments to start with the name of what they describe.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Job79andClaude Opus 5.5 committed 2026-11-19 19:10:54 +01:00
1 parent 8aeb448936
commit db8fb0d5a4
15 files changed
+218 -180

No files matched your search

+64 -29
View File
@@ -1,43 +1,78 @@
# Agent notes
How to build and test this image as a coding agent. Follow [STYLE.md](STYLE.md) for every change.
How to build and test this image as a coding agent. Follow [Style](#style) for
every change.
## Container
## Style
`mkosi vm` needs systemd on the host. A dev container has none, so run mkosi in a podman container that:
- Keep it simple. Prefer fewer files, fewer lines and the defaults. Delete what
isn't needed.
- Divide code and config into parts (files, directories, config sections) that
each stand on their own: reading one alone tells you what it does and why.
- Each fact lives in one place. Elsewhere, refer to it by path instead of
repeating it.
- Write plain English in short sentences.
- boots systemd (`--systemd=always`, with `/sbin/init` as its command)
- is privileged and has `/dev/kvm`
- has `mkosi qemu-kvm-core edk2-ovmf systemd-repart openssh-clients` and `$(mkosi dependencies)` installed
- mounts the repository, such as at `/repo`
### File header
Then run mkosi with `podman exec <container> mkosi ...`.
podman resolves host paths on the host, not in the dev container, so `~` and the scratchpad don't exist there. Mount paths inside the repository instead, such as `./mkosi.output/...`, which is ignored by git.
## Test VM
The `[Runtime]` section of `mkosi.conf` sets up the test VM. It boots a throwaway copy (`Ephemeral=yes`), so every boot is a first boot. The setup takes its answers from credentials: root's password is `test`, and the `claude` user gets the keys in `~/.ssh/*.pub` of whoever runs mkosi (`mkosi.credentials/agent.ssh-key`).
- If the container has no `~/.ssh`, make a throwaway key in `mkosi.output/test-ssh/` and mount it at `/root/.ssh`.
- `mkosi vm` needs a terminal. Without one, run it with `podman exec -d -t` and send its output to a file.
- ssh runs inside the container, which forwards port 2222 to the VM: `podman exec <container> ssh -p 2222 claude@localhost`. Pass `-F /dev/null` if ssh rejects the mounted config because of its owner.
- For root, run `su -` over ssh.
## Image version
`mkosi.version` prints the build time, so every mkosi run has a new version. `mkosi vm` then looks for an image that was never built and fails with "has not been built yet". Either rebuild with `mkosi -f vm`, or boot an existing build by pinning its version:
Every file that allows comments starts with a header. It goes after the
shebang, if there is one:
```sh
mkosi --image-version 202611171816 vm # the version in mkosi.output/agent_<version>.raw
#!/bin/sh
# Image version
#
# Prints the build time in UTC (YYYYMMDDhhmm). Every build gets a higher
# version than the one before, which is how systemd-sysupdate tells that an
# update is newer.
```
Pinning saves a full rebuild when only testing.
- Line 1 is a title: a few words, in sentence case, with no full stop.
- Then a line with only the comment character.
- Then what the file does and why, naming the files it works with by path.
## Boot time
Files that can't hold comments (JSON, `subuid`, `machine-id`) are explained in
the file that uses them.
Measure it over ssh with `systemd-analyze`, `systemd-analyze blame` and `systemd-analyze critical-chain`. In `blame`, the `.device` units only show when udev announced the device, not time spent, so filter them out.
### Comments
The test VM always does a first boot (setup, growfs, enrolling the Secure Boot keys). To measure a normal boot, reboot it with `systemctl reboot` as root: the throwaway copy lasts until qemu exits. Compare a few boots, since timings vary.
- Explain why, not what. Leave out comments that only repeat the code. Try to
write clean code instead of many comments.
- Put a comment right above the line or block it is about.
- Write full sentences that start with the name of what they describe:
`# PackageCacheDirectory keeps downloaded packages between builds.` or
`# cred prints the credential agent.<name>, and fails if it isn't passed.`
- Wrap comments at 80 columns.
To see what systemd waits for, boot with debug logging without a rebuild: `mkosi --kernel-command-line-extra=systemd.log_level=debug vm`.
## Testing
`mkosi vm` boots the image in qemu and needs systemd on the host. Without it,
run mkosi in a privileged podman container that boots systemd:
```sh
podman build -t mkosi-vm - <<'END'
FROM registry.fedoraproject.org/fedora:45
RUN dnf install -y mkosi qemu-kvm-core edk2-ovmf systemd-repart \
openssh-clients socat && \
dnf install -y $(mkosi dependencies)
CMD ["/sbin/init"]
END
podman run -d --name mkosi --privileged --systemd=always -v <repo>:/repo \
-w /repo mkosi-vm
podman exec mkosi mkosi genkey # once, if there is no mkosi.key
podman exec -d -t mkosi sh -c 'mkosi -f vm > mkosi.output/vm.log 2>&1'
podman exec mkosi mkosi ssh -- systemctl --failed
```
podman resolves paths on the host, so `<repo>` is the repository's path there.
`mkosi vm` needs a terminal, hence `-d -t`; its console goes to the log.
`mkosi ssh` runs a command as root, once the VM has booted. For the user
`claude`, run `su - claude -c '<command>'`.
`mkosi.version` gives every run a new version, so `mkosi vm` without `-f` fails
with "has not been built yet". To boot an existing build without a rebuild, pin
its version (from `mkosi.output/agent_<version>.raw`):
```sh
mkosi --image-version 202611171816 vm
```