agentd
For developers who run agentd as a daemon and want its policy to be an instruction released on instruction.md: agentd reads the instruction over MCP, verifies its signature when you pin a publisher, and applies each new version as it is released, without a restart.
What agentd does with an instruction
agentd 1.18 or later speaks MCP 2026-07-28, the only protocol version instruction.md's MCP server accepts, and MCP Events. With the configuration on this page, it:
- reads
instruction://ins_<id>@<ref>from the MCP server at startup, and logsinstruction.loaded; - subscribes to that resource, and listens for the
md.instruction.activityevent, so a release or a ref move makes it read again; - applies the new version at its apply boundary, logged as
instruction.appliedwith the old and new version ids. The servers, skills and workflows the instruction declares apply as the version arrives, unlessagent.instruction.machineryisreload; - verifies the author signature when a
trustpin names a publisher, and refuses an unsigned or wrongly signed version; - creates one binding and reports each version it applies, so it shows on the instruction's Agents card with the version it applied (agentd 1.23.0 or later).
agentd reads the first edition of the language (instruction/1) with the official Rust SDK from 1.21.0. Its own configuration keys are in agentd's configuration reference.
Before you start
Plans On Pro, Team, and Enterprise
- agentd 1.18 or later, a build with the
oauth,mcp-eventsandsignfeatures. agentd's release binaries carry them. 1.27.0 or later asks for the instruction's own events by its id. - A released instruction, and the ref you follow.
stableis never made for you:instruction refs <id> set stable v1creates it. See refs. - An agent credential (API key) for the organization: a client id and a secret that agentd exchanges for tokens on its own. Creating one needs an admin. Each plan's number of agent credentials:
Plans Pro 10 · Team 100 · Enterprise unlimited
Create the agent credential
instruction login --admin
instruction agents create support-desk --org acme --scopes read --scopes read lets it read and follow, nothing more. instruction agents create is an administrator's command, and instruction login --admin gives the permission it asks for. It prints the secret once:
agent agt_<id> (support-desk) in acme
client_id: <client id>
client_secret: <secret> <- shown once; store it now (INSTRUCTION_MD_CLIENT_SECRET)
token_url: https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token
scopes: instructions:read
next: instruction connect --host agentd --agent <client id> --org acme <uri> Store the secret in your secret store now. Agents sign in on their own realm, instruction-md-agents, whose token address is the token_url above. The MCP server's metadata names the people's realm, not this one, so agentd needs token_url written in its configuration. Agent credentials covers rotation, revocation and workspace roles.
Find the instruction's id
agentd follows the instruction by its id, not by its name (see Pin by id):
instruction get acme/support-agent acme/support-agent instruction://ins_<id>
title: Support agent
… Print the configuration
instruction connect --host agentd prints the part of agentd's configuration that reaches instruction.md, filled in with the credential's coordinates (never its secret):
instruction connect --host agentd --agent <client id> --org acme instruction://ins_<id>@stable # agentd 1.18 or later: merge into its configuration (its intelligence, a2a, store)
agent:
instruction:
mcp:
server: instruction-md
resource: "instruction://ins_<id>@stable"
events: [md.instruction.activity]
unavailable: keep
mcp:
servers:
- name: instruction-md
endpoint: https://instruction.md/mcp
auth:
kind: oauth2
grant: client_credentials
token_url: https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token
client_id: <client id>
client_secret: "{{secret:INSTRUCTION_MD_CLIENT_SECRET}}" # the value shown once at creation
scopes: [instructions:read] agent.instruction.mcp: the resource to read and subscribe to, on the server namedinstruction-md, and the event that makes agentd read it again.unavailable: keep: when the server stops answering after startup, agentd keeps serving with the version it holds.mcp.servers[].auth: the client-credentials grant. agentd fetches a token with the secret, and a new one before it expires.{{secret:NAME}}reads the environment variableNAME; agentd refuses a secret written in the file.
A whole daemon
The printed block merges into agentd's own configuration: its model, its store and its A2A listener. A complete file, with a signature pin:
# agentd 1.18 or later, as a daemon: the instruction is the policy every conversation follows
agent:
name: support-desk
instruction:
mcp:
server: instruction-md
# the instruction's id at a ref: publishing moves the ref, and the server pushes the re-read
resource: "instruction://ins_01M…@stable"
events: [md.instruction.activity]
unavailable: keep
trust:
- uri: "instruction://ins_01M…@stable"
publisher: "https://instruction.md/pub/acme"
intelligence:
endpoints: https://api.anthropic.com
dialect: anthropic
model: claude-sonnet-5
token: "{{secret:ANTHROPIC_API_KEY}}"
mcp:
servers:
- name: instruction-md
endpoint: https://instruction.md/mcp
auth:
kind: oauth2
grant: client_credentials
client_id: "<your agent's client id>"
client_secret: "{{secret:INSTRUCTION_MD_CLIENT_SECRET}}"
# agents sign in on their own realm
token_url: https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token
store:
kind: file
file: { path: ./support-desk-state }
a2a:
listen: http://127.0.0.1:8420
lifecycle:
run_until: drained Run it with both secrets in the environment:
export ANTHROPIC_API_KEY=<your model key>
export INSTRUCTION_MD_CLIENT_SECRET=<the agent's secret>
agentd --config support-desk.yaml A daemon needs something that can give it work, here a2a.listen. With lifecycle.run_until: drained it exits only on a signal.
Pin by id or ref
The resource's address decides what agentd follows:
resource: "instruction://ins_<id>@stable" # follows the stable ref: a ref move is a new version
resource: "instruction://ins_<id>@latest" # follows every release
resource: "instruction://ins_<id>@v3" # one version, never another Use the id form, instruction://ins_<id>@<ref>, for two reasons:
- Its subscription is notified. The name form
instruction://acme/support-agent@stablecan be read, and a subscription to it is accepted, but it is never notified: the server's notices name the id form only (Subscriptions). agentd would then hear of a release only through the event, or at its next re-read. - It is what a signature names. An author signature names the instruction by its id address, and agentd compares a
trustpin'suriwith it as written. A pin on the name form refuses every read.
The trust entry names the same id address as the resource, and the publisher whose signature a version must carry, https://instruction.md/pub/<organization>:
agent:
instruction:
mcp:
server: instruction-md
resource: "instruction://ins_<id>@stable"
events: [md.instruction.activity]
unavailable: keep
trust:
- uri: "instruction://ins_<id>@stable" # the same address as resource, in the id form
publisher: "https://instruction.md/pub/acme" With a publisher pinned, an unsigned version is refused, and so is one signed by another publisher. Every version released on instruction.md is signed with the organization's platform key. Signing and verification explains the keys.
Check it worked
- agentd's log shows
instruction.loadedat startup, theninstruction.appliedafter each release that moves the ref you follow. - With agentd 1.23.0 or later,
instruction.binding.reportedfollows eachinstruction.applied, and the instruction's Agents card lists the agent with the version it applied. - Release a version and move the ref (
instruction refs <id> set stable v2). agentd applies it within seconds.
What it doesn't do yet
- Follow by name. A subscription to the name form is never notified, and the name form doesn't match a signature pin: pin by id.
- Report from older releases. agentd before 1.23.0 makes no binding, so the Agents card shows it as a reader without an applied version.
- The agentd profile. The first edition of the specification has an agentd export profile,
agentd/1(profiles/agentd.md, published with the first edition). It describes how one instruction compiles into agentd's native files:agentd.json,guidance.md, workflow JSON and skills. It is a working draft. instruction.md doesn't compile exports with it, and agentd doesn't read it; agentd reads the instruction itself, as above.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
agentd exits 2 at load, naming {{secret:…}} |
The environment variable isn't set. | Export it, or start agentd with --prompt-missing. |
| The token request fails | The token_url is the people's realm, or the secret was rotated. |
Use the token_url printed with the credential (instruction-md-agents). Rotate with instruction agents rotate <id> and update the secret. |
| agentd can't connect to the server | agentd is older than 1.18, so it speaks an older MCP. | Upgrade agentd. |
| agentd exits 6, naming the publisher | The pinned publisher isn't the one that signed the version. | Pin https://instruction.md/pub/<organization> of the organization that releases it. |
| Every read is refused with a pin | The pin's uri uses the name form. |
Use the id form in both resource and trust[].uri. |
| Releases arrive late | The resource uses the name form, so nothing is pushed. | Use the id form. |
| Still stuck | Ask us. |