Quickstart

This page follows one secret from the agent that asks for it, through the person who approves it, back to the command that uses it. It assumes the machine is already logged in to the broker and the agent session is registered; on a machine you set up yourself, log the machine in first and start each agent with agent-secrets register --wait 10 --exec -- <agent>.

No broker yet? Run the local stack and log its helper in, as that page shows. It has no Dispatch: where step 2 says Dispatch, approve with agent-secrets-devrelay, as approving without Dispatch shows. Every terminal output below is real, captured from that stack, whose two secrets are ada@example.com’s: DEMO_READ_TOKEN at the agent tier, which her own sessions get without asking, and DEMO_API_KEY at the human tier, which she approves.

1. The agent asks

An agent names the secrets a command needs and lets agent-secrets run the command with them in its environment. agent-secrets itself never prints a value, but the command is the agent’s choice and can (the printenv below does), so a session holding a grant can read the value: approve a secret only for a session you would trust with the value itself.

agent-secrets DEMO_API_KEY --reason "Deploy the example service" -- ./deploy.sh

• DEMO_API_KEY is the secret’s name, and the name of the environment variable the command gets it in. Name several to get several.
• --reason is what the approver reads. Say what the command is for.
• Everything after -- is the command.

When the secret’s owner and tier grant it automatically, the command runs at once:

$ agent-secrets DEMO_READ_TOKEN -- printenv DEMO_READ_TOKEN
demo-read-token-value

When it needs a person’s approval, agent-secrets says so, with the request’s id, who approves it, and where (the request’s Dispatch page when AGENT_SECRETS_APPROVE_URL names Dispatch’s address, otherwise Credential requests in the Dispatch Inbox), and waits (up to 30 minutes; set --wait to a duration such as 5m to change that) while the approver decides:

$ agent-secrets DEMO_API_KEY --reason "Deploy the example service" -- ./deploy.sh
agent-secrets: request 0eaf43c4-dea5-4d41-8798-c25f6be7d811 is waiting for approval; waiting up to 30m0s
agent-secrets: waiting for ada@example.com to approve it under Credential requests in their Dispatch Inbox

The approver is the one the broker recorded when the agent asked: the secret’s owner, or, for a shared secret, anyone signed in to Dispatch. Tell that person, not whoever you believe owns the secret: a request goes to whomever its owner tag named at the moment it was made. agent-secrets request and agent-secrets status print the same waiting for … line while the request waits. If that person’s approval is refused NOT_APPROVER, something changed after the request was made (Approvals says what each change does). Usually the secret’s owner changed: run agent-secrets cancel <request id> and ask again, and the new request goes to the current owner. If instead the session’s operator withheld one of the names, the request waits on anyone, and the broker still serves that name to the session, the operator can approve it, so ask them. Otherwise no one can approve it: cancel it and request the names separately, one request per approver, leaving out any name the broker no longer serves (approving a request lists every NOT_APPROVER case).

2. The approver decides in Dispatch

The approver (here ada@example.com, the secret’s owner and the operator of the machine the agent runs on) finds the request at the top of their Dispatch Inbox, under Credential requests: a Secret request row naming DEMO_API_KEY and when it was asked. Opening it shows the request’s page:

Field	What it shows
Kind	Secret request
Identifiers	The secrets asked for: DEMO_API_KEY
Enrollment	The session’s kind, runtime and operator: session · example-host-build:2150654:335907311 · ada@example.com
Lifetime	How long a grant would last: Until the session ends, or the --ttl the agent asked for
Requested, Expires	When it was asked, and when it expires undecided
Policy version	The version of the secret policy it was decided under: the SHA-256 of every agent secret’s name, owner, tier and ARN
Approver	ada@example.com
The agent’s stated reason	Deploy the example service

and two buttons, Approve and Deny. The broker records the decision under the login the approver is signed in to Dispatch as; approving a request covers the page in full.

3. The command runs

Once approved, the waiting agent-secrets collects the grant and replaces itself with the command, DEMO_API_KEY set in its environment. This command prints only the value’s length:

$ agent-secrets DEMO_API_KEY --reason "Deploy the example service" -- sh -c 'echo "deploying with a ${#DEMO_API_KEY}-character key"'
deploying with a 18-character key

The grant outlives the command: it lasts until the session ends, unless the agent asked for less with --ttl. Meanwhile the same session asking for exactly the same secrets gets it again without asking anyone; agent-secrets self lists the session’s live grants:

$ agent-secrets self
enrollment_id: 2b8627f4-9a2a-4c12-85bf-910144bc0b5c
kind: session
operator: ada@example.com
lease_expires_at: 2026-10-03T03:36:40Z
grant: f5167d29-1789-4719-8e8c-9aec6f1229e7 (request ce11549a-ab03-4a13-95cf-896961c36fc0, until this session ends)
grant: be34ed2a-78e2-4457-9a75-71283a87c16b (request 7db349e6-ad3c-4f40-86d7-c6a38e899306, until this session ends)

When the answer is no

From a session with no live grant of DEMO_API_KEY (a new session, or one that ran agent-secrets revoke <grant id>), the same command asks again. When the approver clicks Deny (on the local stack, agent-secrets-devrelay deny --record <record id>), nothing runs and agent-secrets exits 77:

$ agent-secrets DEMO_API_KEY --reason "Deploy the example service" -- ./deploy.sh
agent-secrets: request 2375f92d-bab0-4123-a0cb-d139c98de73c was denied

A request still undecided when --wait runs out exits 75 and runs nothing; a name the broker does not serve is refused at once:

$ agent-secrets NO_SUCH_SECRET -- true
agent-secrets: no agent secret has this name (UNKNOWN_SECRET)

Troubleshooting lists every refusal and what to do about it, and Concepts explains sessions, owner and tier, and grants.