Skip to content
Barry Guides
WIP

This guide is a work in progress. Barry is also a work in progress.

Manage secrets

Use this when a tool or a harness needs an API key, and you want Barry to hand the key to what needs it instead of writing it into a prompt.

Before you begin

Section titled “Before you begin”
  • Build a Barry. These commands act as the bonanza identity from that guide; use your own identity’s command in its place.
  • Have administrator rights on your Mac: the vault’s one-time setup runs with sudo.
  • Have the key itself, such as a Linear API key.

How secrets reach a tool

Section titled “How secrets reach a tool”

A tool declares the secrets it needs by name, never by value. When the tool runs, Barry looks up those names, hands the values to the tool’s code, and keeps them out of the model’s context. Logs redact secret values, and displays mask all but a few characters.

A secret has two parts: where Barry keeps the value, and the name an identity binds it to. A secret can come from three places:

Source Declared as Where the value lives
Vault { in: vault, item: <item>, field: password } Barry’s encrypted vault
File { in: .env }, or { in: .env, key: <KEY> } A gitignored .env beside identity.yaml
Keychain { in: keychain, item: <item>, account: <account> } The macOS login Keychain

Set up the vault

Section titled “Set up the vault”

The vault runs as its own macOS user so no other process on your account can read it. Set it up once with system privileges:

Terminal
sudo barry setup --system

Then give your identity a vault account. Provisioning also points the identity at its new vault:

Terminal
bonanza vault provision --email you@example.com

To share one vault among several identities, assign each to it with vault assign.

Add and read secrets

Section titled “Add and read secrets”
Terminal
bonanza vault add LINEAR_API_KEY
bonanza vault list
bonanza vault get LINEAR_API_KEY

add stores or updates a secret, and asks for the value at a masked prompt so it stays out of your shell history; list shows the item names; get prints one value, masked. remove deletes an item.

Reference a secret from an identity

Section titled “Reference a secret from an identity”

Map an environment-variable name to a source in your identity.yaml:

vault: bonanza
secrets:
  LINEAR_API_KEY:
    in: vault
    item: LINEAR_API_KEY
    field: password

The top-level vault: names the vault the identity reads from. Each entry under secrets: maps a variable name a tool declares to where its value comes from. A tool that declares LINEAR_API_KEY now receives the value at call time.

Give the identity a harness key

Section titled “Give the identity a harness key”

Barry runs a harness on the identity’s key for the model’s vendor, never on your own sign-in. identity secret set stores a key and binds it to the identity in one step, so you skip the identity.yaml edit. Barry asks for the value at a masked prompt:

Terminal
bonanza identity secret set ANTHROPIC_API_KEY --in keychain

Use the variable name the vendor reads, such as OPENAI_API_KEY for OpenAI. --in picks where the value lives: keychain for the macOS login Keychain, or vault once the identity has a vault. To see the names the identity binds, run bonanza identity secret list.

Scope secrets to tools

Section titled “Scope secrets to tools”

By default a secret is tool-scoped: Barry hands the value to the tool that declared it, not to the agent’s process environment. Leave it there unless a tool needs a value in its environment. The no-secrets bound adds best-effort guards on top: it blocks the agent’s own file tools from paths such as .env, .ssh, and key files, and withholds the shell and the harness’s native file tools. Neither is a guarantee, so the caution in this guide still applies.

Verify

Section titled “Verify”

Before you rely on an identity, confirm its secrets resolve:

Terminal
bonanza identity check

identity check reports the vault connection, the secrets, and any bag credentials. Each secret gets a line with its source, such as LINEAR_API_KEY: available (vault:LINEAR_API_KEY). bonanza identity test also validates that the secrets load.

If it fails

Section titled “If it fails”
  • A secret shows MISSING. Barry could not read the value from its source. Add it with bonanza vault add, or fix the item or key the identity names.
  • Vault: missing named vault selection. The identity declares a vault secret but no vault:. Add the top-level vault: line, or run bonanza vault assign.
  • Vault: could not open the declared vault. Run bonanza vault status to check the vault’s connection. See A secret is not loading.
  • A tool line reports missing and a name. The tool declares a secret the identity does not map or cannot read. Map the name under secrets:.

What’s next

Section titled “What’s next”