AGENTS.md@main

AGENTS.md

Notes for AI agents working in this repo. Read README.md for the layout and workflow, and docs/fleet-migration-plan.md for where the migration stands.

Deploying

Deploy only with the Justfile (just deploy <fqdn>), never nixos-rebuild on a host. Deploy only when the user asks.
Before deploying, run just diff-host <fqdn> and say what will change. For a refactor, the goal is “identical”.
One behavioural change per deploy. Networking, boot and major upgrades go out with --reboot (the same path as a cold boot), after reading the generated units.
Colmena deploys whole systems: a host must only ever be deployed from this repo, never from a project repo.

Secrets

Never print secret values. Check them by shape (grep -c, byte counts, public-key fingerprints).
Secrets come from the secrets store as Colmena keys (servers.secrets, see README). Nothing secret goes into the repo or the Nix store.

Systemd services and PATH

Scripts here run as systemd services, which have a minimal PATH. Every external binary a script calls must be provided, either through the service’s path, an environment variable with the full path (the existing scripts use $CURL, $RCLONE), or pkgs.writeShellApplication with runtimeInputs (as forge-rebuild-site does).

Working on hosts over SSH

ssh infra.rtw.run goes through ~/.ssh/config, whose IdentityFile is offered even with -i … -o IdentitiesOnly=yes. To test a specific key, use ssh -F /dev/null -o UserKnownHostsFile=~/.ssh/known_hosts -i <key> -o IdentitiesOnly=yes ….
Don’t use pkill -f <pattern> inside ssh host '<command>': the remote shell’s own command line contains the pattern and gets killed. Use PIDs, or pgrep with a [x]yz pattern.
Go’s SSH server (soft-serve on 23231) waits for the client’s version string before sending its own; a bare banner probe looks like a dead port.

infra.rtw.run

The forge: soft-serve (git over SSH 23231, git daemon 9418, HTTP behind Caddy) and kilimanjaro.io, built by pgit from the public repos on every push. See roles/forge/README.md.