Files
agentos/AGENTS.md
T
2026-11-17 21:09:15 +01:00

2.5 KiB

Agent notes

How to build and test this image as a coding agent. Follow 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:

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 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.

To see what systemd waits for, boot with debug logging without a rebuild: mkosi --kernel-command-line-extra=systemd.log_level=debug vm.