<!--
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)
-->

# Setup

## `bento init`

Scaffold `.bento/` in the current directory with a starter `daemon.yaml`, a `pr-review` pipeline, and the `reviewer` persona it runs. The command detects the `origin` git remote and the `gh` login, and fills in `repos:` and `github.username` when it finds them. An existing `agents/reviewer/PERSONA.md` is left as it is.

```bash
bento init
```

| Flag | Description |
|------|-------------|
| `--force` | Overwrite existing `.bento/` files |

## `bento update`

Replace the installed `bento` binary with the latest release from `install.getbento.sh`. Bento verifies the downloaded binary with `--version` before it replaces the running executable. Restart the daemon afterward to use the new version.

```bash
bento update
```

`bento update` swaps the binary only. The daemon keeps running the old version, and database migrations run on daemon restart, so complete an upgrade in order:

```bash
bento update            # replace the binary; daemon still on the old version
bento doctor            # resolve configuration errors before restarting
bento daemon restart    # daemon picks up the new binary and runs migrations
bento daemon status     # confirm the daemon is reachable
```

Migrations are forward-only. After a newer daemon migrates the database, an older binary fails to read it. Snapshot the database first if you need a rollback path. Check each release for version-specific configuration steps.

| Flag | Description |
|------|-------------|
| `--check` | Report whether an update is available without installing it |

## `bento setup gh`

Authenticate a GitHub Agent principal for this daemon instance. With legacy `github.username`, you need no selector. For pipeline principal bindings, pass the canonical reference. If the configuration references exactly one GitHub principal, Bento infers it. Bento stores the credentials under `~/.bento/<name>/gh`. Restart the daemon after authenticating.

```bash
# Interactive browser flow
bento setup gh

# Non-interactive: read token from an environment variable
bento setup gh --env AGENT_GITHUB_TOKEN

# Explicit pipeline principal
bento setup gh --principal github.principal.your-org-review-agent --env REVIEWER_GITHUB_TOKEN
```

| Flag | Description |
|------|-------------|
| `--env <name>` | Read the Agent principal token from this environment variable. Bento verifies the token belongs to the selected login before storing it. |
| `--principal <ref>` | Authenticate a configured canonical GitHub principal such as `github.principal.your-org-review-agent`. |
| `--host` | Also authenticate the machine's default `gh` profile. Requires `--env`. Use it only on a dedicated daemon host where the existing `gh` identity is safe to replace. |

## Encrypted credentials

Linear setup and webhook setup store credentials in Postgres under the daemon's `name`. Set `database.url` in `.bento/daemon.yaml`. For a new installation, run:

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

Setup and the daemon automatically read `~/.bento/<name>/credential-encryption.key`. Keep a secure backup of that file. For a replacement host, restore it with `bento secrets key --import`. See [key management](/cli/secrets) for environment overrides, remote setup, and rotation.

Bento encrypts client secrets, refresh tokens, and webhook secrets with AES-256-GCM. Client IDs and principal IDs remain plaintext. Access tokens stay in memory. For an old file-based OAuth installation, run OAuth setup once to populate Postgres. Encryption-key import does not import OAuth tokens.

## `bento setup linear`

Install the Linear OAuth application as an agent. Complete the [encrypted credential prerequisites](#encrypted-credentials) first.

1. Register `http://localhost:7899/callback` as a redirect URL on the Linear OAuth application.
2. Supply `LINEAR_CLIENT_ID` and `LINEAR_CLIENT_SECRET` through the setup process environment.
3. Run the command from your project directory:

```bash
bento setup linear
```

Bento opens the browser for `actor=app` authorization and exchanges the callback code for tokens. The command writes the installation to Postgres. It does not write tokens to `~/.bento/credentials`.

The command also accepts `linear.client_id` and `linear.client_secret` from `.bento/daemon.yaml`. Environment variables take precedence. After setup, remove those YAML fields and setup variables. The daemon reads the encrypted client secret from Postgres.

The command prints `linear.principal.<app-user-id>`. Bind that reference under `principals:` in your pipeline. Restart the daemon after setup.

For a remote daemon, run setup on that host as the daemon user, from its project directory. Forward local port `7899` to port `7899` on that host before opening the authorization URL. Keep the tunnel open until setup completes. The browser callback uses `localhost` on your computer, so it needs the tunnel to reach the remote setup process.

## `bento setup webhook`

Store a named webhook secret in Postgres. Complete the [encrypted credential prerequisites](#encrypted-credentials) first. Supply the secret through `BENTO_WEBHOOK_SECRET`, or select another variable with `--secret-env`:

```bash
bento setup webhook linear-signing --secret-env LINEAR_WEBHOOK_SECRET
```

Reference the credential in `.bento/daemon.yaml`:

```yaml
webhooks:
  sources:
    linear:
      verify: linear
      secret_ref: webhook/linear-signing
```

Use either `secret_ref` or `secret` on each source. A reference is the full secret name, `webhook/<name>`. A webhook name is lower-case letters and digits, joined by single hyphens. A secret belongs to the current daemon name. Restart the daemon after setup. The daemon decrypts the secret in memory and refuses to start if the reference is missing or unreadable. `bento secrets list` shows the stored names.

## Key rotation

Use [`bento secrets key --rotate`](/cli/secrets#rotate) to rotate the encryption key and database credentials together.

## Lost-key recovery

If a backup exists, restore the original key and version with `bento secrets key --import`. Setup refuses to overwrite unreadable credentials, which protects them from an incorrect key.

If the key is permanently lost, stop the affected daemon. Inspect its rows before deletion:

```sql
SELECT daemon_name, kind, name
FROM daemon_credentials
WHERE daemon_name = 'YOUR_DAEMON_NAME';
```

Delete only the credential that needs replacement. Substitute the exact daemon name, kind (`oauth` or `webhook`), and credential name:

```sql
DELETE FROM daemon_credentials
WHERE daemon_name = 'YOUR_DAEMON_NAME'
  AND kind = 'YOUR_CREDENTIAL_KIND'
  AND name = 'YOUR_CREDENTIAL_NAME';
```

For Linear, use kind `oauth` and name `linear`. After removal of all unreadable rows, use `--generate` if no key file exists, then repeat `bento setup linear`. For each lost webhook credential, repeat `bento setup webhook` with the provider's secret. Replace every unreadable credential that the daemon requires before restart. Deletion discards the stored credential and does not revoke the provider installation.

## `bento setup codex`

Authenticate an isolated Codex subscription credential and register it under a name. Run this from the project directory, where `.bento/daemon.yaml` lives.

```bash
bento setup codex work
```

Bento runs `codex login --device-auth` into a temporary `CODEX_HOME`, stores the resulting `auth.json` under `~/.bento/provider-credentials/codex/<name>/`, and adds a `path`-backed `kind: subscription` entry for `codex.<name>` to `.bento/daemon.yaml`. Restart the daemon to apply it.

| Flag | Description |
|------|-------------|
| `--reauth` | Replace an existing credential of the same name |

## `bento setup claude`

Authenticate an isolated Claude subscription credential and register it under a name. Run this from the project directory, where `.bento/daemon.yaml` lives.

```bash
bento setup claude personal
```

Bento runs `claude auth login --claudeai` into a temporary `CLAUDE_CONFIG_DIR`, stores the resulting `.credentials.json` (or, on macOS, the login's Keychain item) under `~/.bento/provider-credentials/claude/<name>/`, and adds a `path`-backed `kind: subscription` entry for `claude.<name>` to `.bento/daemon.yaml`. Restart the daemon to apply it.

| Flag | Description |
|------|-------------|
| `--reauth` | Replace an existing credential of the same name |
