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

# Authentication

## Bearer tokens

You manage bearer tokens with the command-line interface, and the daemon stores them in its database.

```yaml
# daemon.yaml — static token config (alternative to CLI-issued tokens)
auth:
  tokens:
    - id: cli-prod
      secret: ${BENTO_TOKEN_CLI}
      scopes: ["*"]                                  # every scope
    - id: ci-runner
      secret: ${BENTO_TOKEN_CI}
      scopes: ["pipelines:invoke", "triggers:read"]  # fire pipelines, read triggers
```

## Scopes

A token identifies the caller. A scope grants permission for an operation. Every HTTP route except `/` and `/health` requires a scope. A token with no scopes grants no access.

| Scope | Grants |
| --- | --- |
| `workloads:read` | Read workloads, their invocations, and run artifacts |
| `workloads:write` | Create and close workloads, submit and cancel invocations |
| `workloads:admin` | Read and operate a workload owned by another token |
| `triggers:read` | List and inspect triggers, read `/trace` lineage, read `/notes`, read work graphs |
| `pipelines:invoke` | Fire a pipeline, replay a trigger, dispatch a URL, run a schedule now |
| `knowledge:read` | `POST /ask` and the knowledge listing |
| `repos:read` | The configured repos and their pull requests |
| `evals:write` | List and curate evals, and read eval statistics and cohort comparisons |
| `admin` | Drain, queue status, resume, reconcile, purge, the doctor probes, credential status, and sandbox snapshots |
| `*` | Every scope |

`bento token issue` grants `*`. Tokens declared in `daemon.yaml` grant exactly what they list.

A broker JSON Web Token (JWT) carries its scopes in a space-delimited `scope` claim. A token without this claim authenticates but grants no access. If the claim exists but is not a string, the daemon rejects the malformed token with `401`.

`workloads:read` and `workloads:write` reach only the workloads that the token created. A token needs `workloads:admin` to reach a workload another token owns. That scope is the only one that crosses the boundary. `admin` is daemon lifecycle authority and grants no access to another token's workload. See [Workload ownership](/security#workload-ownership).

The MCP endpoint (`/mcp`) uses its own vocabulary — `mcp:read`, `mcp:write`, `notes:write`, and `host:execute:<name>`, checked per tool. The two vocabularies do not merge.

## Topology

```
Developer machine (Claude Code / Codex)   ← remote topology
       ↓  HTTPS + Bearer token
Tunnel (Tailscale Funnel / Cloudflare)
       ↓
Daemon host (bento daemon)
       ↓  spawns agent in sandbox
Sandbox (podman container)
```

When the editor and the daemon share a machine, you need no tunnel. Connect directly to `http://127.0.0.1:7890/mcp`.

**Local daemon** (same machine as your editor): use `http://127.0.0.1:7890/mcp`. The daemon enforces authentication as soon as any token exists in the store. After you run `bento token issue`, every request requires a bearer token, even on localhost.

**Remote daemon**: expose it through a tunnel (Tailscale Funnel or Cloudflare) and use a token.

## Local credentials (`bento auth setup`)

For a daemon on the same machine, generate the local credential once:

```bash
bento auth setup
```

This writes a token to `~/.bento/credentials` (mode 0600). Every daemon instance on the machine reads this file at startup and accepts the token as a bearer. After the setup, restart each running daemon. `bento ps` lists them.

To reference the token from config files without pasting it, export it in your project `.envrc`:

```bash
# Local daemon credentials token (~/.bento/credentials) — bearer for the bento MCP server
export BENTO_CREDENTIALS="$(jq -r .token "$HOME/.bento/credentials" 2>/dev/null)"
```

## Issuing tokens

On the machine running the daemon, issue a token:

```bash
bento token issue --email you@example.com
```

The command prints a `bento_pat_...` token once, and never shows it again. To replace the existing token for that email address, pass `--force`.

To audit or clean up tokens:

```bash
bento token list
bento token revoke <token-id>
```

## Configuring agents

### Claude Code

Run from your project directory:

```bash
claude mcp add --transport http bento http://127.0.0.1:7890/mcp \
  --header "Authorization: Bearer <token>"
```

This writes to `~/.claude.json` under the current project scope. Pass `--scope user` to share the entry across all projects on this machine.

To avoid pasting the token, reference the `BENTO_CREDENTIALS` environment variable from your `.envrc` (see [Local credentials](#local-credentials-bento-auth-setup)) — Claude Code expands `${VAR}` in MCP config. Add the daemon to `.mcp.json` in the project root (or the same entry under `mcpServers` in `~/.claude.json`):

```json
"mcpServers": {
    "bento": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:7890/mcp",
      "headers": {
        "Authorization": "Bearer ${BENTO_CREDENTIALS}"
      }
    }
}
```

The port matches the root `port:` in `.bento/daemon.yaml` (default 7890). To pick up the changes, restart Claude Code or reconnect through `/mcp`.

### Codex

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.bento]
url = "http://127.0.0.1:7890/mcp"
http_headers = { Authorization = "Bearer <token>" }
```

Restart Codex to pick up the change.

### pi

Set these environment variables in your project `.envrc`:

```bash
export BENTO_DAEMON_URL="http://127.0.0.1:7890"
export BENTO_TOKEN="<token>"
```

Then restart pi to pick up the new environment.
