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

# Security

This page describes the boundaries bento enforces: where an agent runs, what the daemon exposes on the network, how it authenticates a caller, and which credentials reach a run.

## Sandbox isolation

Every agent runs inside a container, under Podman or Docker. The daemon clones the target repository into the container, mounts only the credentials the pipeline declares, and starts the agent command-line interface inside it. Without a configured sandbox backend, the daemon refuses to start an agent. There is no host fallback.

To enforce read-only file access within the sandbox, set `guardrails.read_only: true` in the pipeline config.

## Network exposure

The daemon binds to `127.0.0.1:7890` by default — localhost only, not reachable from outside the machine.

When you expose it via a tunnel (Cloudflare or Tailscale), the public surface is the events endpoint and the MCP endpoint. Both require authentication. A Cloudflare Quick Tunnel has no built-in authentication — the daemon's bearer-token middleware and webhook signature verification are the only gate. Never disable them.

See [Public Access](/public-access) for tunnel setup.

## Workload ownership

A workload belongs to the token that created it. Only that token can read the workload, close it, submit an invocation into it, list its invocations, read one of them, or cancel one.

For unauthorized identifiers, the daemon returns the same status and body as for identifiers that do not exist. This prevents callers from discovering workloads or invocations that belong to another token.

That response is not the same on every route, because an absent identifier is not the same on every route:

| Route | Response to a token that is not the owner |
|-------|-------------------------------------------|
| `GET /workloads/:id` | `404 not_found` |
| `DELETE /workloads/:id` | `404 not_found` |
| `POST /workloads/:id/invocations` | `400 invalid_request` |
| `GET /workloads/:id/invocations` | `200 []` |
| `GET /workloads/:id/invocations/:invocationId` | `404 not_found` |
| `DELETE /workloads/:id/invocations/:invocationId` | `404 not_found` |

Ownership follows the invocation, not the path. A caller that puts its own workload id in the path and another token's invocation id after it gets the response in the table for that route.

`workloads:admin` is the one scope that crosses this boundary. `admin` does not cross it: a token that reads another token's workload cannot also drain the daemon. The `*` wildcard holds both scopes, so a local operator and a token from `bento token issue` keep full access.

The daemon records each decision. A record holds the principal, the route, the resource, and the outcome. It never holds the bearer token. A refusal of an identifier that exists is a warning, because a caller reached for a resource that belongs to someone else.

## Webhook validation

Each webhook source carries its own credential. Set them in `daemon.yaml`:

```yaml
webhooks:
  sources:
    github:
      verify: github
      secret: ${GITHUB_WEBHOOK_SECRET}
  linear: ${LINEAR_WEBHOOK_SECRET}
  tokens:
    deploy: ${BENTO_DEPLOY_WEBHOOK_TOKEN}
```

Each source under `webhooks.sources` declares the check its requests pass: `verify: github` and `verify: linear` are HMAC-SHA256 over the raw request body, and `verify: bearer` is a static bearer token. A `linear` source also requires the delivery's own `webhookTimestamp` to be within a minute, so a captured delivery fails on replay. Register the same value at the source. The daemon compares in constant time and rejects a bad or missing credential with `401`. It does this before it parses the body, so a rejected request records no event and starts no agent. Every rejection returns the same status and the same body, so a caller does not tell a wrong credential from an unconfigured route.

If a pipeline triggers on a webhook source with no usable credential while the daemon is reachable off the machine, it exits at startup. It does not serve unverified webhooks. The rule covers GitHub, Linear, and each generic webhook name. A loopback bind is exempt only while nothing publishes it — a configured `tunnel:` counts as reachable, because it makes the loopback-bound port public.

See [Configuration](/configuration#webhooks) for the full field reference.

## API authentication

The daemon's HTTP and MCP endpoints require a bearer token as soon as any token exists in the store. After the first `bento token issue`, every request requires authentication, even on localhost.

A token carries scopes, and a scope is what grants authority. Every route except `/` and `/health` requires one, so a token with no scope authenticates and does nothing:

```yaml
auth:
  tokens:
    - id: ci-runner
      secret: ${BENTO_TOKEN_CI}
      scopes: ["pipelines:invoke"]
```

Daemon lifecycle routes — drain, queue resume, reconcile, purge — require `admin`. Give a CI token the verbs it needs and nothing more.

Revoke tokens individually with `bento token revoke <id>` without touching other issued tokens. See [Authentication](/authentication) for the full token reference.

## Credential scoping

The agent receives only the credentials you explicitly mount into the sandbox. A pipeline without `sandbox.mounts` holds no token for a push, a comment, or any external service.

Match mounts to what the pipeline actually needs:

```yaml
sandbox:
  mounts:
    - host: ~/.config/gh
      container: /home/node/.config/gh
```

For GitHub actions, use a fine-grained personal access token scoped to the specific repos and permissions the pipeline requires. See [Identity](/identity) for how to set up an Agent principal with minimal permissions.

## Prompt injection

Webhook payloads carry user-controlled content — PR titles, commit messages, Linear ticket descriptions, issue comments. That content is rendered into the agent prompt. A malicious actor with write access to those fields injects instructions into the prompt.

Practical mitigations:

* **Validate the event source** — HMAC webhook verification ensures payloads come from the registered source (GitHub, Linear), but not that the payload content is safe.
* **Scope skills narrowly** — give each skill one task. See [Context Engineering](/context-engineering).
* **Restrict write credentials** — an agent without push or comment credentials takes no action on an injected instruction, even when it follows one.
* **Review traces** — `bento trace <trigger-id>` shows the full prompt the agent received. Audit pipelines that accept public input (open-source repos, public Linear boards).
