Using af with your coding agent

af is built to be driven by coding agents. Once you have finished Getting started, your agent runs af under your user, with exactly your Lane’s rights and no more.

Point your agent at the docs

Give your agent one line:

Read https://docs.atominfra.com/llms.txt and use af to manage my machines.

/llms.txt lists every page. /llms-full.txt has the whole site in one plain-text file, and /llms-small.txt is a shorter version for small context windows. The same guide is installed next to af, at "$(npm root -g)/@sq/atominfra/af.md".

Rules for agents

Follow these every time.

1. Always pass --json and parse the output. Never scrape the human-readable text; it may change.
2. Check the exit code. On failure, read error.code and do what Errors and what to do says for that code.
3. Creating is safe to retry. create with a name that already exists returns the existing machine with "created": false, as long as the kind and size match. After a timeout, retry with the same name instead of making a second one.
4. Never delete a Box unless the user asked you to. Every delete needs --confirm <name>. A Box holds their work.
5. Clean up what you start. Delete Runners you created for a task when it is done.
6. Secrets go on stdin only. Never put a token, a key or a password in a name, a label, an argument or a file af uploads. af runner register and af login read theirs on stdin.
7. Stay in your Lane. You can see and reach only the user’s machines. Do not scan or probe other addresses: probing another Lane breaks the platform’s rules even when it fails, and isolation is audited.
8. Do not loop on limits. On LANE_LIMIT or HOST_FULL, wait retryAfterSeconds once or use a smaller size; otherwise stop and tell the user.
9. Ask the user before growing anything to size L or above, and before anything that restarts a Box (RESTART_REQUIRED).

What the user does, not the agent

• af login: setup, with the one-time token.
• Registering a Runner with GitHub: the user’s own GitHub credential creates the token, piped into af. The agent never holds it.
• Opening the web console: it is for people; agents always use af.

Output

Every command prints exactly one JSON object with --json:

{ "ok": true, "data": { "...": "..." } }

{ "ok": false, "error": { "code": "LANE_LIMIT", "message": "...", "hint": "..." } }

Logs go to stderr. The command reference lists the keys of data for every command.