Set up approved secret access for coding agents.

Start with the signed macOS release.

Homebrew installs the notarized app into /Applications and links the bundled agent-secret command into Homebrew's bin directory.

brew tap kovyrin/agent-secret https://github.com/kovyrin/agent-secret
brew install --cask agent-secret
agent-secret skill-install
agent-secret doctor

Run agent-secret doctor after install or upgrade. It prepares the background helper if needed and checks the socket directory, audit log, native approver, and 1Password desktop integration without resolving any item references. agent-secret install-cli also tries to refresh the local background helper after repairing the command symlink.

Use op:// refs for desktop-backed secrets.

Agent Secret uses the 1Password desktop app SDK integration. In 1Password, open Settings -> Developer and enable Integrate with other apps under Integrate with the 1Password SDKs.

agent-secret exec --reason "Run Terraform plan" \
  --secret CLOUDFLARE_API_TOKEN=op://Example/Cloudflare/token \
  -- terraform plan

Agents can inspect item metadata without seeing values: agent-secret item describe --format env-refs "op://Example Infra/Database Credentials".

Use bws:// refs for Bitwarden secrets.

Bitwarden support uses the official Bitwarden-signed bws CLI and a local macOS Keychain token alias. Agent Secret v1 supports official Bitwarden cloud endpoints and looks for bws at fixed common paths such as /opt/homebrew/bin/bws and /usr/local/bin/bws.

agent-secret bitwarden secrets-manager token install --alias work
agent-secret bitwarden secrets-manager token status --alias work

The token install command uses hidden terminal input by default. Use --from-stdin only for scripts that already hold the token outside shell history.

Commit references and request metadata, never values.

Put agent-secret.yml or .agent-secret.yml at the project root. Profiles keep the reason, TTL, references, and provider disambiguation in the repo so an agent can request a known workflow without carrying raw credentials.

version: 1
default_profile: deploy

sources:
  bitwarden:
    work-secrets:
      kind: secrets_manager
      token_alias: work

profiles:
  deploy:
    account: Example Corp
    reason: Deploy application
    ttl: 10m
    session:
      bind: parent
    secrets:
      CLOUDFLARE_API_TOKEN: op://Example/Cloudflare/token
      RELEASE_WEBHOOK:
        ref: bws://5f3f59f6-cb33-4d7a-9f92-86f75b5ce4c1
        source: work-secrets

With default_profile, running agent-secret exec -- terraform plan from the project directory uses that profile. Use --profile NAME when a repo has multiple workflows.

Approve a bag once, then run bounded commands.

Sessions are for short workflows where an agent needs the same approved set of references in different combinations. Agent Secret stores values in background helper memory and returns a public session ID for management plus a secret session token for with-session calls from the same requester process tree.

agent-secret session create \
  --profile terraform-cloudflare \
  --bind-parent \
  --max-reads 3 \
  --json=compact
agent-secret with-session astok_123 --only CLOUDFLARE_API_TOKEN -- terraform plan
agent-secret with-session astok_123 \
  --only CLOUDFLARE_API_TOKEN,STATE_TOKEN \
  -- terraform apply
agent-secret session list
agent-secret session destroy asid_123

session create can combine a project profile, env files, and one-off --secret ALIAS=REF flags. Use --json=compact when a shell wrapper needs one JSON object on one line. Keep the returned session_token for with-session; use the returned or listed session_id for inspection and cleanup. session list never reveals session tokens. with-session injects every approved alias by default, or a per-command subset with --only. Unknown aliases fail before the child command starts. Use sessions inside one task shell, wrapper script, or agent process tree.

Session tokens are bound to the requester process tree by default. Use --bind-parent when a wrapper creates the session inside command substitution and later calls with-session from the parent shell. Deeper wrappers can use --bind-ancestor N up to 3; Agent Secret accepts only ancestors of the current agent-secret process, not arbitrary PIDs. When the wrapper depth varies across accepted agents, repeat --bind-ancestor-name NAME; it matches the nearest eligible ancestor executable basename in the allowed set within the current ancestry. Profiles can set session.bind: parent, session.bind: auto, session.bind: { ancestor: N }, or session.bind: { ancestor_name: NAME } / session.bind: { ancestor_names: [NAME, ...] }. Session list JSON includes non-secret binding metadata so process mismatch failures are easier to debug.

Sessions end when TTL passes, the read count is exhausted, session destroy succeeds, or the helper stops. V1 sessions do not expose raw socket reads or long-lived interactive shells.

Check requests without leaking values.

Use --dry-run --json to inspect exactly what an agent is about to ask for. Dry runs do not start the background helper, prompt for approval, resolve secret values, or spawn the child process.

agent-secret exec --dry-run --json --profile deploy -- terraform plan

For a live smoke test, print metadata only. Lengths and hashes are enough to prove delivery without exposing the secret:

agent-secret exec \
  --reason "Bitwarden smoke test" \
  --secret BITWARDEN_SMOKE=bws://work/00000000-0000-0000-0000-000000000000 \
  -- python3 -c 'import os, hashlib; v=os.environ["BITWARDEN_SMOKE"].encode(); print(len(v), hashlib.sha256(v).hexdigest()[:12])'

Most failures are setup or trust state.

Short answers for common integration questions.