# Agent notes How to build and test this image as a coding agent. Follow [Style](#style) for every change. ## Style - 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. ### File header Every file that allows comments starts with a header. It goes after the shebang, if there is one: ```sh #!/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. ``` - 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. Files that can't hold comments (JSON, `subuid`, `machine-id`) are explained in the file that uses them. ### Comments - 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., and fails if it isn't passed.` - Wrap comments at 80 columns. ## 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 \ -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 `` 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 ''`. `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_.raw`): ```sh mkosi --image-version 202611171816 vm ```