diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f577f7e --- /dev/null +++ b/AGENTS.md @@ -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 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 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_.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. diff --git a/README.md b/README.md index 6137c9f..7259d93 100644 --- a/README.md +++ b/README.md @@ -29,12 +29,11 @@ mkosi build `mkosi.output/` then holds the disk image (`agent_.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 -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`). - -`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. +[AGENTS.md](AGENTS.md) has the details, such as testing from a dev container.