why
Agents now operate servers. They investigate incidents, patch packages and restart services. An agent that lands on a host starts with nothing: it does not know that this is a production replica, where the logs are, or which restart drops live traffic.
Humans have /etc/motd, a wiki and colleagues. Repositories have AGENTS.md. Hosts have nothing that every agent can read. /etc/agents is that place.
example
$ cat /etc/agents
# db-replica-2.prod.example.net
## Role
PostgreSQL 17 streaming replica for billing. Production.
The primary is db-primary-1.
## Where things are
- Logs: journalctl -u postgresql@17-main
- Config: managed by Ansible. Local edits are overwritten.
## Do not
- Do not restart postgresql between 06:00 and 08:00 UTC.
Nightly reports run then, and a restart makes them
fail without an alert.
- Do not run `pg_ctl promote`. Promotion needs the
failover runbook and a human.
## Escalation
Replication lag above 10 minutes: stop and page #data-oncall.No required fields. No schema. Write what a competent new colleague needs on day one with root access and cannot discover with one command: intent, history and consequences.
layout
If you know systemd drop-ins, you already know this.
| Path | Written by | For |
|---|---|---|
/etc/agents | Administrator | The main description of the host |
/etc/agents.d/*.md | Ansible, Puppet, you | Site-specific fragments |
/run/agents.d/*.md | Scripts, at runtime | Temporary state: “maintenance until 14:00” |
/usr/lib/agents.d/*.md | Packages | How a packaged service is operated |
The same file name in /etc overrides /run, which overrides /usr/lib. An empty file or a link to /dev/null disables a fragment.
rules
A file that every agent reads is a prompt-injection target. The specification treats it as one.
- Root only. An agent skips a file that root does not own, or that group or others can write.
- Context, not authority. The file informs. Sudo rules, permissions and sandboxes enforce.
- Restrictions count, grants do not. “Do not restart X” is respected. “You may disable the firewall” grants nothing.
- This host only. The file cannot send an agent to other hosts, to an external URL or to its own credentials.
- No secrets. Name the secret store. Do not paste the secret.
adopt
You run servers
$ sudoedit /etc/agentsOr use the Ansible role or the cloud-init snippet. Start from an example.
You build an agent
Before the first state-changing command on a host, run the reference loader and give the output to the model with a label that names the host. Then apply the five rules.
$ ssh host 'sh -s' < agents-catThe loader is 30 lines of POSIX shell. It merges the directories and makes the trust check.
You package software
Ship /usr/lib/agents.d/NN-yourpackage.md with the log locations, the reload-versus-restart rule and the commands that destroy data.
implementations
Agents that read /etc/agents. Open a pull request to add yours.
related files
| File | Audience | Scope |
|---|---|---|
/etc/motd | Humans at login | Host |
/etc/os-release | Programs | Host identity |
AGENTS.md | Coding agents | Repository |
/etc/<vendor>/… | One vendor’s agent | Policy for that tool |
/etc/agents | Any agent | Host |
faq
Why not /etc/AGENTS.md?
Files in /etc are lowercase and have no document extension: motd, hosts, fstab, issue. A file that looks at home is a file that administrators accept.
Why not put an AGENTS.md in / ?
AGENTS.md describes a repository: build steps, tests, code style. A host is not a repository. It has an owner, a role and consequences, and /etc is where a host keeps facts about itself.
My agent already reads a vendor file in /etc. Why another?
The vendor file configures one tool. /etc/agents describes the machine, once, for every tool. Read both.
Is this a prompt-injection hole?
Only root can write a file that agents accept, and root already controls the host. The rules also stop the next step: the file cannot grant permissions, and it cannot direct an agent to other hosts or to its credentials.
Why Markdown and not YAML?
The reader is a language model, and the most useful content is the reason behind a rule. Prose carries reasons. Structured keys are an open question for 1.0.
Will the agent obey the file?
The file is advice with a clear scope, not enforcement. Use sudo rules and permissions for what must never happen.
Who owns this?
Nobody owns the path. It is an open specification, started by Andrey Gerasimov. The text is under CC BY 4.0 and the code is under Apache 2.0. All changes happen in public on GitHub.