The image now holds only the ESP and a verity-protected /usr (A/B). At first boot, systemd-repart in the initrd makes the root filesystem: btrfs, encrypted with a TPM key sealed to the signed PCR 11 policy, with /var as its own subvolume. A TPM is required. systemd.image_policy= accepts only an encrypted root and a verity-checked /usr, and FactoryReset=yes lets factory-reset.target wipe it. /etc is writable but nearly empty: mkosi.finalize keeps the build's /etc in /usr/share/factory/etc and systemd-tmpfiles links it in at boot. That removes etc-shadow.mount, the host key on /var, fstab and /var/lib/agent. /var now survives reboots. systemd-firstboot replaces agent-setup: it asks for the root password on the screen and offers a recovery key. Machines are named agent-???? from the kernel command line. The user is now agent, with its home in /home/agent and ssh keys in the default places. sshd.path starts sshd only once root or agent has a key. The test VM needs swtpm. The package cache moves to a podman volume (AGENTS.md). No existing VMs can update to this layout. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2.9 KiB
Agent notes
How to build and test this image as a coding agent. Follow 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, sections) that each stand on their own: reading one part 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:
#!/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:
# ManifestFormat lists the packages and versions in the image.or# link prints the tmpfiles line for /etc/$1. - 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:
podman build -t mkosi-vm - <<'END'
FROM registry.fedoraproject.org/fedora:45
RUN dnf install -y mkosi qemu-kvm-core edk2-ovmf systemd-repart swtpm \
openssh-clients socat && \
dnf install -y $(mkosi dependencies)
CMD ["/sbin/init"]
END
podman run -d --name mkosi --privileged --systemd=always -v <repo>:/repo \
-v mkosi-cache:/root/.cache/mkosi -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 <repo> is the repository's path there.
The volume mkosi-cache keeps mkosi's package cache when the container is
made again, so builds don't download every package anew.
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
agent, run su - agent -c '<command>'.
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_<version>.raw):
mkosi --image-version 202611171816 vm