docs: move testing details from README to AGENTS.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Job79andClaude Opus 5.5 committed 2026-11-17 19:33:00 +01:00
1 parent 3b791adc3d
commit 2439f58279
2 files changed
+43 -5

No files matched your search

+39
View File
@@ -0,0 +1,39 @@
# Agent notes
How to build and test this image as a coding agent. Follow [STYLE.md](STYLE.md) for every change.
## Container
`mkosi vm` needs systemd on the host. A dev container has none, so run mkosi in a podman container that:
- 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`
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:
```sh
mkosi --image-version 202611171816 vm # the version in mkosi.output/agent_<version>.raw
```
Pinning saves a full rebuild when only testing.
## Boot time
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. The test VM has one CPU and always does a first boot (setup, growfs), so a real VM boots faster.