Files
agentos/AGENTS.md
T
Job79andClaude Opus 5.5 94fd5d1ce9 fix: check out with git, sign local builds with a test key
gitea-runner 6 has no builtin:checkout, and plain Fedora has no Node.js
for actions/checkout, so the workflow fetches the commit with git.
Setting permissions: keeps read access for that and asks for package
writes.

mkosi genkey won't replace mkosi.crt, so the docs now sign local builds
with a test key in mkosi.local.conf, which also covers the PCR and
verity keys.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 16:07:45 +00:00

100 lines
4.3 KiB
Markdown

# 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 and fewer lines. Delete what isn't
needed. Write plain English in short sentences.
- Follow the defaults and conventions of each tool and language. Only set an
option when the default doesn't work.
- Each fact lives in one place. Elsewhere, refer to it instead of repeating it.
- 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.
- Name each part for what it does. A part without a good name holds things
that don't belong together.
- A little copying beats a little dependency. Repeat a small piece rather than
share it or pull it in from elsewhere.
### File header
A file starts with a header, after the shebang if there is one. Leave it out
when the name already says it all, as with `.gitignore`. A part made of
many files, like a package, needs it in only one file. For example:
```sh
#!/bin/bash
# mkosi.version prints the build time in UTC (YYYYMMDDhhmm) and the git
# commit. Every build gets a higher version than the one before, which is how
# systemd-sysupdate tells that an update is newer. The commit tells which
# source an image was built from.
```
- The first sentence starts with the name of the part the file is, and says
what it does. That is the name the language or tool uses for it, such as a
file name or a package name.
- The rest says 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 comments.
- 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.`
- Put a comment right above the line or block it is about. A short note on
one line may go at the end of that line, as a full sentence too.
- Separate paragraphs and lists with a line holding only the comment
character.
- Wrap comments at 80 columns.
## Testing
`mkosi vm` boots the image in qemu. It needs systemd on the host, so 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 git-core qemu-system-x86-core edk2-ovmf swtpm-tools \
virtiofsd openssh-clients socat
CMD ["/sbin/init"]
END
podman run -d --name mkosi --privileged --systemd=always -v <repo>:/repo \
-v mkosi-cache:/root/.cache/mkosi -v mkosi-work:/var/tmp -w /repo mkosi-vm
podman exec mkosi mkdir -p mkosi.cache
podman exec -d -t mkosi sh -c 'mkosi -i -f \
--kernel-command-line-extra=console=ttyS0 vm -- -serial chardev:console \
> mkosi.output/vm.log 2>&1'
podman exec mkosi mkosi ssh -- systemctl --failed
```
- mkosi signs with the test key of `mkosi.local.conf`
([README.md](README.md#development)), with paths as the container sees them.
- `mkosi -i` keeps the image with its packages installed in `mkosi.cache/`.
Rebuilds start from it and skip installing packages.
- The volume `mkosi-work` keeps mkosi's workspace in /var/tmp off overlayfs.
When mkosi copies files with SELinux labels to overlayfs, it drops all
xattrs. That removes the file capabilities of newuidmap and newgidmap, and
rootless podman fails in the VM.
- `mkosi vm` needs a terminal, hence `-d -t`. Its console goes to the log.
- The console of `mkosi vm` is hvc0, which the kernel can only use once the
initrd loads its driver. `console=ttyS0` also sends the kernel log to the
serial port, and `-serial chardev:console` sends that port to the same log.
The log then shows early errors too, such as a panic or an initrd that
can't find /usr. Arguments after `--` go to qemu.
- `mkosi ssh` runs a command as root once the VM has booted. For the user
`agent`, run `su - agent -c '<command>'`.
`mkosi.version` gives each run a new version, so `mkosi vm` without `-f` fails
with "has not been built yet". To boot an existing build again, pin its version
from `mkosi.output/agentos_<version>.raw`:
```sh
mkosi --image-version 202611171816.c80e843 vm
```