<!--
Sitemap:
- [Installation](/installation): Install the Bento daemon on macOS or Linux, then write your first pipeline to run a coding agent on a GitHub, Linear, or schedule event.
- [Upgrading](/upgrading): Version-specific steps for upgrading an existing Bento install.
- [Concepts](/concepts)
- [Build your first pipeline](/tutorials/pipeline-args)
- [Target a specific issue or PR from a URL](/tutorials/url-targeting)
- [Keep state across runs](/tutorials/pipeline-state)
- [Fire a pipeline on a schedule or on demand](/tutorials/schedule-and-fire)
- [Deploy a box to Railway](/tutorials/deploy-to-railway)
- [Operate a hosted daemon](/tutorials/operate-a-hosted-daemon)
- [Configuration](/configuration): Configure the Bento daemon with daemon.yaml: service name, port, webhooks, sandboxes, knowledge base, and environment variables.
- [Members](/members)
- [Knowledge base](/knowledge-base/)
- [Method and delivery](/knowledge-base/modes): Choose how Bento retrieves knowledge (BM25, vector, or hybrid) and how it delivers that knowledge to a coding agent.
- [Config](/knowledge-base/config)
- [MCP](/knowledge-base/mcp): Give coding agents your team knowledge over MCP. The Bento daemon serves an ask_knowledge search tool and per-file resources.
- [Pipeline configuration reference](/pipelines/config): Reference for Bento pipeline YAML: triggers, agents, skills, instructions, filters, sandboxes, structured results, and outputs.
- [Filters](/pipelines/filters): Filter GitHub, Linear, and webhook events by repository, label, and other fields so only the right Bento pipelines run.
- [Triggers](/triggers/): Start a Bento pipeline from a GitHub, Linear, webhook, schedule, or manual trigger. Compare the trigger types and when each one fires.
- [GitHub trigger](/triggers/github): Run a coding agent on GitHub pull request, issue, and other webhook events. Configure HMAC verification and event patterns.
- [Linear trigger](/triggers/linear): Run a coding agent on Linear issue and comment events. Configure the Linear webhook, signature verification, and Hookdeck relay.
- [Webhook trigger](/triggers/webhook): Fire a Bento pipeline from any HTTP POST to /webhooks/{name}, with bearer-token authentication declared in daemon.yaml.
- [Schedule trigger](/triggers/schedule)
- [Manual trigger](/triggers/manual): Fire any Bento pipeline on demand with bento trigger fire, and pass typed inputs to a pipeline that runs only on request.
- [Traces](/pipelines/traces)
- [Slack](/integrations/slack)
- [Public access](/public-access): Expose the Bento daemon to GitHub webhooks through a Cloudflare Quick Tunnel or Tailscale Funnel, and compare the two options.
- [Context engineering](/context-engineering): Assemble each coding agent prompt from personas, policies, skills, and pipeline instructions. Learn which file each instruction belongs in.
- [Best practices](/best-practices)
- [Troubleshooting](/troubleshooting)
- [Architecture](/architecture/vision)
- [Workspaces](/workspaces)
- [Authentication](/authentication)
- [Identity](/identity)
- [Security](/security)
- [References](/references)
- [Changelog](/changelog): Bento release history.
- [CLI reference](/cli/)
- [Setup](/cli/setup)
- [Secrets](/cli/secrets)
- [Lifecycle](/cli/lifecycle)
- [Sandbox image](/cli/image)
- [Sandboxes](/cli/sandbox)
- [Observability](/cli/observability)
- [Diagnostics](/cli/diagnostics)
- [Triggers](/cli/triggers)
- [Workbench](/cli/workbench)
- [Auth](/cli/auth)
- [Knowledge](/cli/knowledge)
- [Evals](/cli/evals)
- [Bento docs: run coding agents from version-controlled pipelines](/index): Bento runs coding agents from pipelines you keep in your repository. Declare the trigger, sandbox, skill, and guardrails in YAML.
- [Runtime wrapper](/architecture/runtime-wrapper)
- [Skill evolve](/architecture/skill-evolve)
-->

# Secrets

`bento secrets` manages the stored secrets of the current daemon name. Run it from the project directory. A secret has a full name, `<kind>/<leaf>`. The kind names the consumer, such as `webhook/github` or `sandbox/cloudflare-api-key`. Each segment is lower-case letters and digits, joined by single hyphens. Configuration refers to a secret through a `_ref` field that holds the full name, such as `secret_ref: webhook/github`. A pipeline reads a secret into a run through a `{name, secret, required?}` entry of its [`env` manifest](/pipelines/config#env). No command prints a secret value.

## Sources

`secrets.instance` in `.bento/daemon.yaml` selects the source that holds the secrets of this daemon. The default is `postgres`. `secrets.company: sops` selects an encrypted file for shared secrets. OAuth names stay in the instance source; other names use the company source when configured. The `cloud` company source requires a Bento Cloud identity and is not available on a local daemon.

```yaml
secrets:
  instance: postgres
```

| Source | Store | Writes |
| --- | --- | --- |
| `postgres` | The `daemon_credentials` table, encrypted under the [key file](#key-location) | `bento secrets set`, `bento setup webhook`, `bento setup linear` |
| `env` | The environment of the daemon, as `BENTO_SECRET_<KIND>__<LEAF>` | None. The platform sets the variables. |
| `sops` | An existing encrypted YAML or JSON file | `bento secrets set` |
| `keyring` | The keyring of the operating system, through `security` on macOS and `secret-tool` on Linux | `bento secrets set` |

The `env` source maps a name to a variable in upper case. A `-` becomes `_`, and the `/` between the two segments becomes `__`. `sandbox/cloudflare-api-key` reads `BENTO_SECRET_SANDBOX__CLOUDFLARE_API_KEY`. The `env` source needs no key file and no database. A Linear principal binding needs the `postgres` source, because the Linear installation lives only there.

The `keyring` source is for a developer host. It stores each secret as a keyring item with the service `bento-<name>` and the account `<kind>/<leaf>`, and it needs no key file and no database. It needs an unlocked keyring, so a headless service does not use it. The macOS keyring cannot enumerate its items, so `bento secrets list` prints `The macOS keyring cannot list secrets; check a name with bento doctor.` there, and `bento doctor` reports each `_ref` through a lookup. On Linux, `secret-tool` has no lookup that reads no value, so `has` and `list` read the value inside the daemon process and discard it. A value must not contain a line break, because each tool reads one command for each line. On macOS a value is at most 2048 bytes and contains only printable ASCII, because `security` reads one line of bounded length and prints another value as hexadecimal. Store another value in the `postgres` source. After a write, the source reads the value back and compares it, and it deletes the item when the two differ. `bento doctor` also reports where PATH resolves the keyring tool.

## Legacy names

A webhook secret that an earlier version stored under a name with `_` or upper case stays in the table, and you can list and delete it, but no `secret_ref` can name it. `bento doctor` lists each such name. Delete it with `bento secrets rm <name>`, then store it again under a name that matches the grammar.

## Store a secret

Pipe the value into `bento secrets set`. The command does not accept a value as an argument. It removes one trailing newline.

```bash
printf %s "$CLOUDFLARE_API_TOKEN" | bento secrets set sandbox/cloudflare-api-key
```

Each write increments the version of that name. `bento secrets list` prints each name, its version, and its update time. `bento secrets rm <name>` deletes one secret. `bento doctor` reports each `_ref` in the configuration as stored, not stored, or not reachable. It reads no value.

## Key

`bento secrets key` manages the encryption key of the `postgres` source for the current daemon name. Run it with `database.url` set in `.bento/daemon.yaml`. The command checks that database before a key change. It never prints key material.

## Key location

Setup and daemon boot read `~/.bento/<name>/credential-encryption.key` automatically. The JSON file contains the Base64-encoded key and its integer version. Its permissions are `0600`. Keep a secure backup outside the database and repository.

Run key import as the daemon's operating-system user. If provisioning creates the directories, give that user ownership of both `~/.bento` and `~/.bento/<name>`. Bento also writes workspace state under `~/.bento/workspaces`. A readable key does not prove that the parent directory permits those writes.

An explicit `BENTO_CREDENTIAL_ENCRYPTION_KEY` environment variable overrides the file. Its value is a Base64-encoded 32-byte key. `BENTO_CREDENTIAL_ENCRYPTION_KEY_VERSION` defaults to `1`. An invalid override fails without fallback to the file. Unset the override before key management commands, so the daemon does not ignore the new file.

## Generate

For a new installation:

```bash
bento secrets key --generate
```

Bento generates 32 cryptographically random bytes and saves version `1`. It refuses generation if the key file exists or the database contains credentials for this daemon name. A missing key for existing credentials requires a backup, not a new random key.

## Import

Restore a key from a secure backup through standard input:

```bash
bento secrets key --import < /secure/backup/credential-encryption.key
```

Import accepts the JSON key file, which preserves its version. It also accepts a raw Base64 key as version `1`. Use JSON for a rotated key. Key values are not command-line arguments.

Bento checks the imported key against every database credential for this daemon before it replaces the local file. A wrong key leaves the local file unchanged. On a replacement host, use the same daemon name and database. OAuth setup is not required again after a successful key restore.

Only encryption keys support import. These commands do not import OAuth tokens from the old credentials file.

## Rotate

Stop all processes for the affected daemon name before rotation. Then run:

```bash
bento secrets key --rotate
```

Bento generates a new key, increments the version, and re-encrypts the database credentials. The command then saves the new local key. Securely distribute the resulting JSON key file to other hosts for this daemon name before restart. Use `--import` on each receiving host. Refresh the secure backup after rotation.

During rotation, the file holds the current key and a `pending` key. The database updates occur in one transaction. If rotation stops between the database commit and file replacement, rerun the same command. It resumes with the pending key rather than generating another one. File-based setup and boot refuse to proceed until the pending rotation completes.

Do not manually remove a pending key or distribute a pending file. If another host completed rotation, import that host's final key file instead.

The old `bento setup rotate-credential-key` command is replaced by `bento secrets key --rotate`. External secret systems still support environment injection. To rotate an externally injected key, import the current key into the local file first, without an active environment override. After rotation, update the external secret system with the new key and version before restart.

For a permanently lost key with no backup, see [lost-key recovery](/cli/setup#lost-key-recovery).

## SOPS files

Install [SOPS 3.11.0 or later](https://github.com/getsops/sops/releases/tag/v3.11.0) on the daemon host. Bento uses `sops set --value-stdin`, introduced in that release. The daemon needs access to the decryption identity.

```yaml
secrets:
  instance: postgres
  company: sops
  sops:
    file: secrets.dev.yaml
```

Create and encrypt the file before startup. Paths resolve from the project root. Store full secret names as top-level keys with nonempty string values. Bento passes values through stdin and atomically replaces an encrypted copy. Use `instance: sops` without a company slot when all non-OAuth secrets belong in that file. Linear principal bindings still require `instance: postgres`.
