Walkthrough

Before you start, the agent’s machine needs the helper installed and running (agent-secrets-helper install --url <broker address>), with its operator (the person who approves for the machine) named in ~/.config/agent-secrets/operator, and AGENT_SECRETS_URL set to the broker’s address in the shells agents start from. The machine also sets AGENT_SECRETS_APPROVE_URL to Dispatch’s address, which makes agent-secrets machine login print Dispatch’s machine-login page to open. Log a machine in sets all of this up.

A narrated tour of one secret request, recorded on example data: the Dispatch workspace’s person is alice@example.com, the agent’s machine is example-host-build, and the secret, DEMO_API_KEY, holds a made-up value. The steps below are the ones the video shows, with a still of each page.

1. Log the machine in, once

On the agent’s machine, agent-secrets machine login prints a code and the address of Dispatch’s machine-login page, /credentials/machine. Alice opens that page, types the code, and checks the record it finds: a machine login for example-host-build, with her as its approver. She approves it, the page lists it under Machine logins, where Revoke would end it and every session it started (end a machine’s login), and the login on the machine returns. agent-secrets machine login-status checks the machine login at any time: it prints issued while the machine holds one, and says when that login lapses. The helper refreshes it every day, and resumes it after a restart, so the machine logs in once.

2. Start a session

agent-secrets register --wait 10 --exec -- bash registers a session with the machine’s helper, as an agent’s session is registered when it starts, and runs a shell in it. agent-secrets self shows the session’s enrollment and its operator, alice@example.com.

3. Ask for the secret

The session asks for the secret to run one command, and says why:

agent-secrets DEMO_API_KEY --reason "Publish the docs preview for PR 42 with the demo API" -- ./check-demo-key.sh

DEMO_API_KEY is alice’s own secret at the human tier (its tags are owner=alice@example.com and tier=human), so a request for it waits for her approval, even from her own machine: the command waits, and names who approves it, alice, and the request’s page on the secrets broker, where she decides it.

4. Approve it

The request is at the top of alice’s Inbox, under Credential requests, and counts toward Needs you beside the sidebar’s Inbox. The row is a link to the request’s page on the secrets broker. The stills in this step come from Dispatch’s browser test harness, whose request is a pod’s request for alice’s secret ALICE_DEPLOY_KEY; the page is the same for any request.

The link opens the request’s page on the broker. The browser in the video holds no broker session yet, so the link passes through the broker’s sign-in, which signs alice in and brings her to the page; with a session already held it opens at once. The page prints, from the broker’s own record, what was asked for, by which enrollment, why, for how long, who may approve it and its state. The request named no --ttl, so its grant lasts 15 minutes for a human-tier secret and 12 hours for any other, or less if the session ends first.

She clicks Approve on the broker’s page, and the page says what became of the request.

5. The command runs

The waiting command checks the broker every few seconds, waiting at most 10 seconds between two checks, so it carries on within seconds of the approval: it receives DEMO_API_KEY in its environment and runs. The video shortens that wait. In the recording 11.7 seconds passed between the click and the command’s output on screen: one such interval, plus the grant the command then collected and the work it then did. The demo command prints the key’s length and last four characters to show it arrived. agent-secrets status <request> names who decided the request.

6. The live grant

Settings lists the live grants of alice’s sessions, whether granted automatically or approved, and those she approved on anyone’s session, each with its session, how it was granted and when it expires: this one when the session ends. Revoke ends a grant at once; a command already running keeps the value it was given.

The rig that records the screenshots and the narrated recording, and the scripts that record them again, are in docs/site/media/broker/. The Secrets Broker’s introduction says what the broker is for.