Files
agentos/AGENTS.md
T
Job79andClaude Opus 5.5 db8fb0d5a4 feat: root adds the ssh keys, mkosi ssh for the test VM
The setup no longer asks for an ssh key. Root logs in on the console and
adds keys for claude and root to /var/lib/agent. Root may log in with
ssh, and its home is a tmpfs that is wiped at every boot. The test VM
uses mkosi ssh instead of a forwarded port, so the agent.ssh-key
credential is gone.

Also mount /var with noatime, move STYLE.md into AGENTS.md and rewrite
comments to start with the name of what they describe.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 19:10:54 +01:00

2.7 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, 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:

#!/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.<name>, 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:

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>:/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 <repo> 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 '<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