docs: move testing details from README to AGENTS.md
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2 files changed
+43
-5
No files matched your search
@@ -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.
|
||||||
@@ -29,12 +29,11 @@ mkosi build
|
|||||||
|
|
||||||
`mkosi.output/` then holds the disk image (`agent_<version>.raw`) and the UKI and root partitions that make up an update.
|
`mkosi.output/` then holds the disk image (`agent_<version>.raw`) and the UKI and root partitions that make up an update.
|
||||||
|
|
||||||
To build and boot a test VM with Secure Boot (needs `qemu-kvm-core edk2-ovmf`):
|
To build and boot a test VM (needs `qemu-kvm-core edk2-ovmf`):
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
mkosi -f vm
|
mkosi -f vm # log in as root, password test
|
||||||
|
ssh -p 2222 claude@localhost # with your own key
|
||||||
```
|
```
|
||||||
|
|
||||||
The `[Runtime]` section of `mkosi.conf` answers the setup, so it boots straight to a login (root, password `test`). Then `ssh -p 2222 claude@localhost` with your own key (`mkosi.credentials/agent.ssh-key`).
|
[AGENTS.md](AGENTS.md) has the details, such as testing from a dev container.
|
||||||
|
|
||||||
`mkosi vm` needs systemd on the host. Without it, such as in a dev container, run mkosi in a privileged container that boots systemd and has `mkosi qemu-kvm-core edk2-ovmf systemd-repart openssh-clients` and `$(mkosi dependencies)` installed, with `/dev/kvm` and the repository mounted.
|
|
||||||
Reference in new issue
Block a user