Skip to content
Legion

agent-secrets CLI

agent-secrets is the command an agent session runs to use a secret; agent-secrets-helper is the per-user daemon that signs for a host’s agent sessions. This page is their own help.

agent-secrets

Section titled “agent-secrets”
usage:
  agent-secrets keygen --out <dir>
      Write a new signing key to <dir>/key.pem and print its thumbprint. A box's launcher runs it
      inside the box before enrolling it.
  agent-secrets enroll --helper --runtime-id <id> --thumbprint <tp> [--session-id <id>]
      Enroll a session key a launcher holds (a box's) through this machine's agent-secrets-helper,
      write the enrollment id to AGENT_SECRETS_KEY_DIR/enrollment, and print it.
  agent-secrets unenroll --helper --enrollment <id>
      End an enrollment `enroll --helper` made, through this machine's agent-secrets-helper.
  agent-secrets machine login
      Log this machine in: print the confirmation code its operator types into Dispatch, then wait
      for the decision (exit 0 once approved, 1 when denied or expired).
  agent-secrets machine login-status
      Print "issued" and exit 0 while this machine's helper holds a launcher credential; otherwise
      print the last login's state and exit 1.
  agent-secrets machine list [--json]
      List your own machines' logins that can still reach a secret, under this machine's login:
      each one's id, host, who approved it, when it was issued and expires, and whether it has
      expired with sessions still running. Dispatch's machine-login page lists the same, and every
      service's login beside them.
  agent-secrets machine revoke <credential_id>
      End one of your own machines' logins under this machine's login, as Dispatch's machine-login
      page does: it enrolls nothing more, and every session it enrolled ends. Revoking this
      machine's own login ends this machine's broker access too.
  agent-secrets grant list [--json]
      List the live grants of your sessions and those you approved, under this machine's login:
      each one's id, secrets, how it was granted, who approved it, its session and operator, and
      when it expires. Dispatch's Live grants page lists the same.
  agent-secrets grant revoke <grant_id>
      End a grant as its operator or approver, under this machine's login, as Dispatch's Live
      grants page does. Ending an automatic grant also makes its session ask before it gets those
      secrets again.
  agent-secrets register [--wait SECONDS] [--exec -- COMMAND [ARGS...]]
      Register this process with agent-secrets-helper as a machine session. With --exec, run COMMAND
      as this same process, so it and everything it starts are that session.
  agent-secrets identity
      Exit 0 when this process has a broker identity and 1 when it does not, asking the broker
      nothing.
  agent-secrets --version
      Print the release this binary was built as.
  agent-secrets renew [--pod-token-file FILE]
      Keep an agent box's or pod's enrollment lease alive, renewing it until interrupted. A pod
      names its projected service-account token's file: each renewal sends the token the file holds
      then, which the broker checks names the pod and service account the enrollment was made for.
      POD_TOKEN_REQUIRED, ENROLLMENT_NOT_LIVE, or an older broker's PROOF_INVALID saying
      "not live" exits 76, naming the enrollment, HTTP status and broker code; every other
      refusal retries.
  agent-secrets request NAME... [--reason TEXT] [--ttl DURATION] [--json]
      Request secrets and print the request's id and state, and who approves it and where while
      it waits; exit 75 while it waits for approval and 77 when it is denied. The grant lasts
      --ttl, or until this session ends.
  agent-secrets status <request_id> [--json]
      Print a request's state, who approves it and where while it waits, its grant once
      granted, and who decided it.
  agent-secrets cancel <request_id>
      Cancel one of this session's pending requests.
  agent-secrets revoke <grant_id>
      End one of this session's grants.
  agent-secrets self [--json]
      Print this session's enrollment, operator, lease, and live grants.
  agent-secrets whoami [--json]
      Print this session's enrollment as the broker's JSON, as self --json does.
  agent-secrets sign --method M --url U [--enrollment E]
      Print the proof this session would sign for one broker call, without making the call.
  agent-secrets secret list [--json] [--profile P]
      List every agent secret under your own cloud sign-in: its owner, tier, whether it has a
      value, and, while it is scheduled for deletion, when it was deleted and the earliest it
      can be purged.
  agent-secrets secret show NAME [--json] [--profile P]
      Print the agent secret NAME's owner, tier, dates and versions, never its value.
  agent-secrets secret create NAME --owner me|shared --tier agent|human [--profile P]
      Create the agent secret NAME under your own cloud sign-in, then ask the broker to serve it at
      once. Its value is read from standard input, or typed at a prompt with echo off when standard
      input is a terminal.
  agent-secrets secret set NAME [--profile P]
      Give the agent secret NAME a new value under your own cloud sign-in, then ask the broker to
      serve it at once. The value is read from standard input, or typed at a prompt with echo off
      when standard input is a terminal.
  agent-secrets secret retag NAME [--owner me|shared] [--tier agent|human] [--profile P]
      Change the agent secret NAME's owner, tier or both under your own cloud sign-in, then ask
      the broker to reread it. A shared secret's owner and tier are an administrator's to
      change.
  agent-secrets secret delete NAME [--profile P]
      Schedule the agent secret NAME's deletion, restorable for 30 days, under your own cloud
      sign-in, then ask the broker to stop serving it at once.
  agent-secrets secret restore NAME [--profile P]
      Cancel the agent secret NAME's scheduled deletion under your own cloud sign-in, then ask
      the broker to serve it again at once.
  agent-secrets NAME... [--reason TEXT] [--wait DURATION] [--ttl DURATION] -- <command> [args...]
      Request secrets, wait up to --wait (default 30m) for a person to decide, and run <command>
      with each granted secret in its environment under its NAME; nothing runs unless all are
      granted. The grant lasts --ttl, or until this session ends.


environment:
  AGENT_SECRETS_URL          the broker's base URL; every form that calls the broker needs it
  AGENT_SECRETS_KEY_DIR      an agent box's or pod's key.pem and enrollment
                             (default $XDG_RUNTIME_DIR/agent-secrets, used when key.pem is there)
  AGENT_SECRETS_HELPER_SOCK  a machine session's agent-secrets-helper socket
  AGENT_SECRETS_ENROLL_WAIT  how long a call waits while a box's launcher is still enrolling it
                             (default 20s)
  AGENT_SECRETS_APPROVE_URL  Dispatch's address; machine login names the page under it where the
                             operator types the code, and a waiting request names the page where
                             its approver decides it
  OMP_SESSION_ID             the agent session the broker names and notifies if a pending request
                             expires; falls back to ENVOY_SESSION_ID, then CLAUDE_CODE_SESSION_ID,
                             so a harness that sets one of those instead still names its session
  AWS_PROFILE                the AWS profile the secret forms sign in with when --profile names
                             none (else the AWS SDK's default credential chain); every secret
                             form needs a sign-in in the broker's account, and a write your own
                             Identity Center sign-in there


exit codes: 0 done, 1 failed, 2 usage error, 75 still waiting for approval, 76 permanent renewal refusal, 77 denied;
register --exec exits 127 when COMMAND is not found and 126 when it cannot run;
secret create and set end by the signal on hang-up (SIGHUP), interrupt (Ctrl-C), quit (Ctrl-\)
or termination (SIGTERM) at the value prompt: a shell reports 129, 130, 131 or 143

agent-secrets keygen

Section titled “agent-secrets keygen”
usage: agent-secrets keygen --out <dir>


Write a new signing key to <dir>/key.pem and print its thumbprint. A box's launcher runs it
inside the box before enrolling it.


flags:
  -out string
      directory to write key.pem into

agent-secrets enroll

Section titled “agent-secrets enroll”
usage: agent-secrets enroll --helper --runtime-id <id> --thumbprint <tp> [--session-id <id>]


Enroll a session key a launcher holds (a box's) through this machine's agent-secrets-helper,
write the enrollment id to AGENT_SECRETS_KEY_DIR/enrollment, and print it.


flags:
  -helper
      enroll through this machine's agent-secrets-helper, which holds its launcher credential (required: a launcher credential is a key held only by a helper or a launcher, never a token this CLI could read)
  -kind string
      "box" (accepted for agentbox compatibility)
  -runtime-id string
      this runtime's stable id
  -session-id string
      the agent session the broker notifies if one of this session's pending requests expires
  -thumbprint string
      the signing key's RFC 7638 thumbprint

agent-secrets unenroll

Section titled “agent-secrets unenroll”
usage: agent-secrets unenroll --helper --enrollment <id>


End an enrollment `enroll --helper` made, through this machine's agent-secrets-helper.


flags:
  -enrollment string
      the enrollment id to revoke
  -helper
      unenroll through the local agent-secrets-helper socket

agent-secrets machine login

Section titled “agent-secrets machine login”
usage: agent-secrets machine login


Log this machine in: print the confirmation code its operator types into Dispatch, then wait
for the decision (exit 0 once approved, 1 when denied or expired).

agent-secrets machine login-status

Section titled “agent-secrets machine login-status”
usage: agent-secrets machine login-status


Print "issued" and exit 0 while this machine's helper holds a launcher credential; otherwise
print the last login's state and exit 1.

agent-secrets machine list

Section titled “agent-secrets machine list”
usage: agent-secrets machine list [--json]


List your own machines' logins that can still reach a secret, under this machine's login:
each one's id, host, who approved it, when it was issued and expires, and whether it has
expired with sessions still running. Dispatch's machine-login page lists the same, and every
service's login beside them.


flags:
  -json
      print the broker's response body verbatim

agent-secrets machine revoke

Section titled “agent-secrets machine revoke”
usage: agent-secrets machine revoke <credential_id>


End one of your own machines' logins under this machine's login, as Dispatch's machine-login
page does: it enrolls nothing more, and every session it enrolled ends. Revoking this
machine's own login ends this machine's broker access too.

agent-secrets grant list

Section titled “agent-secrets grant list”
usage: agent-secrets grant list [--json]


List the live grants of your sessions and those you approved, under this machine's login:
each one's id, secrets, how it was granted, who approved it, its session and operator, and
when it expires. Dispatch's Live grants page lists the same.


flags:
  -json
      print the broker's response body verbatim

agent-secrets grant revoke

Section titled “agent-secrets grant revoke”
usage: agent-secrets grant revoke <grant_id>


End a grant as its operator or approver, under this machine's login, as Dispatch's Live
grants page does. Ending an automatic grant also makes its session ask before it gets those
secrets again.

agent-secrets register

Section titled “agent-secrets register”
usage: agent-secrets register [--wait SECONDS] [--exec -- COMMAND [ARGS...]]


Register this process with agent-secrets-helper as a machine session. With --exec, run COMMAND
as this same process, so it and everything it starts are that session.


flags:
  -exec
      after registering, exec the command that follows as this same process
  -wait int
      wait up to this many seconds for the helper to enroll the session (0 returns at once, as does a helper holding no launcher credential)

agent-secrets identity

Section titled “agent-secrets identity”
usage: agent-secrets identity


Exit 0 when this process has a broker identity and 1 when it does not, asking the broker
nothing.

agent-secrets renew

Section titled “agent-secrets renew”
usage: agent-secrets renew [--pod-token-file FILE]


Keep an agent box's or pod's enrollment lease alive, renewing it until interrupted. A pod
names its projected service-account token's file: each renewal sends the token the file holds
then, which the broker checks names the pod and service account the enrollment was made for.
POD_TOKEN_REQUIRED, ENROLLMENT_NOT_LIVE, or an older broker's PROOF_INVALID saying
"not live" exits 76, naming the enrollment, HTTP status and broker code; every other
refusal retries.


flags:
  -pod-token-file string
      a pod's projected service-account token file, read again before every renewal

agent-secrets request

Section titled “agent-secrets request”
usage: agent-secrets request NAME... [--reason TEXT] [--ttl DURATION] [--json]


Request secrets and print the request's id and state, and who approves it and where while
it waits; exit 75 while it waits for approval and 77 when it is denied. The grant lasts
--ttl, or until this session ends.


flags:
  -json
      print the response body verbatim
  -reason string
      why these secrets are needed
  -ttl duration
      how long the grant lasts, a whole number of seconds such as 2m or 90s; unset, it lasts until this session ends

agent-secrets status

Section titled “agent-secrets status”
usage: agent-secrets status <request_id> [--json]


Print a request's state, who approves it and where while it waits, its grant once
granted, and who decided it.


flags:
  -json
      print the response body verbatim

agent-secrets cancel

Section titled “agent-secrets cancel”
usage: agent-secrets cancel <request_id>


Cancel one of this session's pending requests.

agent-secrets revoke

Section titled “agent-secrets revoke”
usage: agent-secrets revoke <grant_id>


End one of this session's grants.

agent-secrets self

Section titled “agent-secrets self”
usage: agent-secrets self [--json]


Print this session's enrollment, operator, lease, and live grants.


flags:
  -json
      print the response body verbatim

agent-secrets whoami

Section titled “agent-secrets whoami”
usage: agent-secrets whoami [--json]


Print this session's enrollment as the broker's JSON, as self --json does.


flags:
  -json
      print the response body verbatim

agent-secrets sign

Section titled “agent-secrets sign”
usage: agent-secrets sign --method M --url U [--enrollment E]


Print the proof this session would sign for one broker call, without making the call.


flags:
  -enrollment string
      sign for this enrollment id instead of this process's own (file mode only)
  -method string
      HTTP method of the call
  -url string
      absolute URL of the call

agent-secrets secret list

Section titled “agent-secrets secret list”
usage: agent-secrets secret list [--json] [--profile P]


List every agent secret under your own cloud sign-in: its owner, tier, whether it has a
value, and, while it is scheduled for deletion, when it was deleted and the earliest it
can be purged.


flags:
  -json
      print the secrets as JSON
  -profile string
      the AWS profile to sign in with (AWS only; default: AWS_PROFILE, else the AWS SDK's default credential chain)

agent-secrets secret show

Section titled “agent-secrets secret show”
usage: agent-secrets secret show NAME [--json] [--profile P]


Print the agent secret NAME's owner, tier, dates and versions, never its value.


flags:
  -json
      print the secret as JSON
  -profile string
      the AWS profile to sign in with (AWS only; default: AWS_PROFILE, else the AWS SDK's default credential chain)

agent-secrets secret create

Section titled “agent-secrets secret create”
usage: agent-secrets secret create NAME --owner me|shared --tier agent|human [--profile P]


Create the agent secret NAME under your own cloud sign-in, then ask the broker to serve it at
once. Its value is read from standard input, or typed at a prompt with echo off when standard
input is a terminal.


flags:
  -owner string
      me (your email, from your AWS or Google sign-in) or shared
  -profile string
      the AWS profile to sign in with (AWS only; default: AWS_PROFILE, else the AWS SDK's default credential chain)
  -tier string
      agent (its owner's agents use it without asking) or human (a person approves each use)

agent-secrets secret set

Section titled “agent-secrets secret set”
usage: agent-secrets secret set NAME [--profile P]


Give the agent secret NAME a new value under your own cloud sign-in, then ask the broker to
serve it at once. The value is read from standard input, or typed at a prompt with echo off
when standard input is a terminal.


flags:
  -profile string
      the AWS profile to sign in with (AWS only; default: AWS_PROFILE, else the AWS SDK's default credential chain)

agent-secrets secret retag

Section titled “agent-secrets secret retag”
usage: agent-secrets secret retag NAME [--owner me|shared] [--tier agent|human] [--profile P]


Change the agent secret NAME's owner, tier or both under your own cloud sign-in, then ask
the broker to reread it. A shared secret's owner and tier are an administrator's to
change.


flags:
  -owner string
      the new owner: me (your email, from your AWS or Google sign-in) or shared
  -profile string
      the AWS profile to sign in with (AWS only; default: AWS_PROFILE, else the AWS SDK's default credential chain)
  -tier string
      the new tier: agent or human

agent-secrets secret delete

Section titled “agent-secrets secret delete”
usage: agent-secrets secret delete NAME [--profile P]


Schedule the agent secret NAME's deletion, restorable for 30 days, under your own cloud
sign-in, then ask the broker to stop serving it at once.


flags:
  -profile string
      the AWS profile to sign in with (AWS only; default: AWS_PROFILE, else the AWS SDK's default credential chain)

agent-secrets secret restore

Section titled “agent-secrets secret restore”
usage: agent-secrets secret restore NAME [--profile P]


Cancel the agent secret NAME's scheduled deletion under your own cloud sign-in, then ask
the broker to serve it again at once.


flags:
  -profile string
      the AWS profile to sign in with (AWS only; default: AWS_PROFILE, else the AWS SDK's default credential chain)

agent-secrets NAME… – command

Section titled “agent-secrets NAME… – command”
usage: agent-secrets NAME... [--reason TEXT] [--wait DURATION] [--ttl DURATION] -- <command> [args...]


Request secrets, wait up to --wait (default 30m) for a person to decide, and run <command>
with each granted secret in its environment under its NAME; nothing runs unless all are
granted. The grant lasts --ttl, or until this session ends.


flags:
  -reason string
      why these secrets are needed
  -ttl duration
      how long the grant lasts, a whole number of seconds such as 2m or 90s; unset, it lasts until this session ends
  -wait duration
      how long to wait for a pending request (default 30m0s)

agent-secrets-helper

Section titled “agent-secrets-helper”
usage:
  agent-secrets-helper [serve]     run the helper: listen on its socket, sign for the machine sessions
                                   registered with it, and enroll each with the broker
  agent-secrets-helper sessions    list live sessions: pid, runtime id, enrollment id, state
  agent-secrets-helper --version   print the release this binary was built as


environment:
  AGENT_SECRETS_URL            the broker's base URL; serve needs it
  AGENT_SECRETS_HELPER_SOCK    the helper's socket
                               (default $XDG_RUNTIME_DIR/agent-secrets/helper.sock)
  AGENT_SECRETS_OPERATOR_FILE  a file holding the operator's Dispatch login, which a machine login
                               names as its approver (default ~/.config/agent-secrets/operator)