Agent Secret

Agent Secret docs

Set up approved secret access for coding agents.

Install the local macOS app, connect either 1Password or Bitwarden Secrets Manager, keep references in project profiles, and validate requests without printing secret values.

Last updated: June 7, 2026

Install

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 starts the daemon if needed and checks the socket directory, audit log, native approver, and 1Password desktop integration without resolving any item references.

1Password

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.

Reference shape

Use the same references 1Password copies for item fields: op://Vault/Item/field. The reference stays in config; the resolved value is delivered only after approval.

Account selection

If there is one usable desktop account, Agent Secret can infer it. If multiple accounts make a request ambiguous, set account in config or pass --account. 

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".

Bitwarden Secrets Manager

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.

Reference shape

Use bws://<secret-uuid> when a single source is available, or bws://<source-alias>/<secret-uuid> when multiple Bitwarden sources need disambiguation.

What "source" means

Source is Agent Secret terminology. For Bitwarden Secrets Manager, a source is a local config alias that points at one local token alias. It is not a Bitwarden UI object.

Project profiles

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
    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.

Validation

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 daemon, 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])'
Troubleshooting

Most failures are setup or trust state.

macOS says bws cannot be verified.

Use the official Bitwarden-signed binary. If you downloaded it manually, clear Gatekeeper quarantine only after verifying the source and checksum. Homebrew-installed bws under /opt/homebrew/bin/bws avoids most path issues.

Bitwarden token reads require repair.

Reinstall the token alias with the currently installed released CLI: agent-secret bitwarden secrets-manager token install --alias work. This refreshes the macOS Keychain access control for the app bundle that will resolve the token.

Doctor reports an untrusted daemon peer.

An old development daemon may still be listening on the socket. Stop it with the matching old CLI or restart the Mac, then run /opt/homebrew/bin/agent-secret doctor again.

Approval is denied because the computer is locked.

Agent Secret refuses to show native approval while the screen is locked. Unlock the Mac and rerun the command.

FAQ

Short answers for common integration questions.

Does Agent Secret store raw secret values?

It does not write raw secret values to project files or audit logs. Reusable approvals may keep approved values in daemon memory until the TTL or use count expires, then they are cleared.

Can an approved child process leak a secret?

Yes. Agent Secret is an approval broker, not a sandbox. After approval, the child process receives the environment variable and can use or leak it like any other process with that value.

Why does 1Password use account while Bitwarden uses source?

A 1Password account is provider identity. A Bitwarden source is local Agent Secret routing metadata that selects a token alias. Both are shown only to make ambiguous references explicit.

Can I mix 1Password and Bitwarden in one profile?

Yes. Each secret reference keeps its own provider metadata, and approval, audit, reuse, and cache matching include that metadata.