# Configuration `bento init` creates these configuration files in your project directory: * **`.bento/daemon.yaml`** — daemon-wide settings * **`.bento/pipelines/*.yaml`** — one file per pipeline (see [Pipeline Config](/pipelines/config)) Runtime state lives under `~/.bento//` and is never committed. Environment variables expand with `${VAR}` syntax in both files. *** ## Identity ```yaml name: bento ``` Sets the launchd/systemd service name and the runtime directory (`~/.bento//`). Make it unique per machine when you run several daemon instances. *** ## Port ```yaml port: 7890 ``` The port for the daemon's HTTP server, which serves both webhooks and the CLI API. CLI commands read this from the project config automatically, so the daemon of each project runs on its own port with no flags. Defaults to `7890`. Supersedes the legacy `webhooks.port`. *** ## GitHub ```yaml github: username: your-org-agent ``` Sets the GitHub Agent principal used by daemon API calls, post-backs, git attribution, and actor runs. `username` is required when any pipeline has a GitHub trigger, GitHub output, or repo-backed checkout, and when the top-level `repos` map is non-empty. Authenticate it with `bento setup gh` or `bento setup gh --env AGENT_GITHUB_TOKEN`. Credentials live under `~/.bento//gh`. On a dedicated daemon host, add `--host` to authenticate the machine's default `gh` profile too. This is the single-principal compatibility form. A pipeline instead declares [principal bindings](/identity#principal-bindings) and selects a canonical GitHub principal at each actor boundary. The top-level `repos` HTTP API still requires `github.username` because it has no pipeline execution boundary. *** ## Linear ```yaml linear: client_id: ${LINEAR_CLIENT_ID} client_secret: ${LINEAR_CLIENT_SECRET} ``` Sets the OAuth application that Bento installs in a Linear workspace as an agent. Both fields are required when the block is present. `bento setup linear` prefers `LINEAR_CLIENT_ID` and `LINEAR_CLIENT_SECRET` from the environment over the corresponding YAML fields. It completes the `actor=app` installation and stores encrypted credentials in Postgres under the daemon's `name`. It does not write tokens to `~/.bento/credentials`. Complete the [encrypted credential prerequisites](/cli/setup#encrypted-credentials) before setup. Remove the YAML fields and setup variables afterward. The daemon reads the client secret from Postgres. The command prints `linear.principal.` for use in [principal bindings](/identity#principal-bindings). *** ## Database ```yaml database: url: postgresql://bento:bento@localhost:8421/bento ``` PostgreSQL connection string. **Required** — the daemon refuses to boot without it, and there is no built-in default (a silent fallback could land two daemons on the same database). An unset `${VAR}` reference expands to empty, which counts as unset. The quickstart Compose file starts Postgres on port `8421` with the credentials shown above. *** ## Webhooks ```yaml webhooks: host: 127.0.0.1 sources: github: verify: github secret: ${GITHUB_WEBHOOK_SECRET} linear: verify: linear secret: ${LINEAR_WEBHOOK_SECRET} deploy: verify: bearer secret: ${BENTO_DEPLOY_TOKEN} ``` The daemon listens for inbound webhook payloads here (on the root `port:` above). Each entry under `sources` is one inbound source. The key names the route. `verify` selects the check for requests to that route. | `verify` | Check | |---|---| | `github` | HMAC-SHA256 over the raw body, against `x-hub-signature-256` | | `linear` | HMAC-SHA256 over the raw body, against `linear-signature`, plus a `webhookTimestamp` within one minute | | `bearer` | `authorization: Bearer ` | A source named `` serves `/webhooks/`, and `/events` is an alias for the `github` route. How a pipeline reaches a source follows `verify`, not the key. `verify: bearer` delivers a generic event under the source's own name, so a pipeline reaches it with `trigger.webhook: []`. `verify: github` and `verify: linear` deliver GitHub and Linear events, so a pipeline reaches them with `trigger.github` and `trigger.linear` whatever the source is called. That makes a second GitHub-signed sender an extra route rather than an extra trigger name: ```yaml sources: gh-enterprise: verify: github secret: ${GHE_WEBHOOK_SECRET} ``` Deliveries to `/webhooks/gh-enterprise` verify against that secret and then match `trigger.github` alongside the `github` source's own. A `trigger.webhook: [gh-enterprise]` that points at it fails at startup, because that trigger never fires. Set a `github` or `linear` secret to the signing secret the provider shows you. For `bearer` you pick the value and give it to the caller. Use `secret_ref` instead of `secret` to load a stored secret from the [secrets source](/cli/secrets#sources) of the daemon: ```yaml webhooks: sources: linear: verify: linear secret_ref: webhook/linear-signing ``` A reference is the full secret name, `/`, in lower case with hyphens. Store the secret with `bento setup webhook linear-signing`, or pipe a value into `bento secrets set webhook/linear-signing`. Each source accepts exactly one of `secret` and `secret_ref`. A reference that does not match the name grammar fails validation, and the message names the full form. The daemon resolves references within its own `name` and rejects a missing or unreadable secret at boot. Resolved secrets stay outside the cached configuration. See [secrets](/cli/secrets) and [key rotation](/cli/secrets#rotate). The daemon rejects a request that fails its check with `401`, before it parses the body or records an event. The daemon rejects a route with no source the same way, so a caller learns nothing about which sources exist. See [Security](/security#webhook-validation). Before `sources`, credentials were `webhooks.secret`, `webhooks.linear`, and `webhooks.tokens.`. All three are gone. If the daemon finds one at startup, it names the replacement. *** ## Targets ```yaml targets: claude-high: runtime: claude model: claude-opus-5-5 effort: high credential_pool: [max-0x, max-1x, max-2x] claude-backup: runtime: claude model: claude-sonnet-5 credential: max-0x codex-high: runtime: codex model: gpt-5.6-sol effort: high credential: oai-personal description: strong non-Claude route for a diverse second opinion on code ``` Defines reusable execution targets. Each target binds a runtime, model, optional reasoning effort, and credential selection. `credential` selects one fixed named credential. `credential_pool` selects a non-empty ordered list of unique credentials. A pool mixes subscription and API-key credentials. A target sets one field or the other, never both. `dispatchable: false` hides a target from the orchestrator's per-task catalog, so the model cannot name it in a `task` dispatch. The target stays valid as a pipeline `targets:` route and as an orchestrator route — the opt-out covers model-chosen dispatch only. Targets default to dispatchable. `description` is an optional note on what the route is good at. The orchestrator's per-task catalog renders it after the route facts, so the model reads `codex-high (codex/gpt-5.6-sol, effort high) — strong non-Claude route for a diverse second opinion on code` instead of the route facts alone. Write it to steer a choice the model already makes: which target suits a scout, which suits the core work, which pair gives a jury two different model families. A target without a description renders as before. The daemon rejects a description that is empty or longer than 140 characters, because the whole catalog goes into every orchestrated run's prompt. The field is operator-authored, and the daemon copies only the target name, runtime, model, effort, and description into the catalog. A credential name never reaches the model. Pipelines, the orchestrator, capabilities, MCP and HTTP invocations, `bento ask`, and knowledge rewrite reference targets. On quota or authentication failure, Bento tries each credential in a target's pool within the same run before advancing to the next target in the route. A subscription cap — session, daily, weekly or monthly — cools that credential down until the reset time it reports. A cooldown window is fixed once it opens: a cap reported again while the credential is already cooling does not move the reset further out, so repeated failures cannot hold a credential that has recovered. Bento retests a cooling credential about every 45 minutes, so a reset time longer than the real cap clears early instead of standing until the reported instant. Cooling the last live credential of a runtime shortens the window to 15 minutes rather than honouring the reported reset, so a runtime that loses its whole pool recovers without an operator. Authentication failure has two different consequences, and the difference is which channel reported it. Fallback within the current run is the weaker one. Any authentication error Bento can classify — from the agent's stderr, from a spawn error, from the runtime's own verdict — advances the run to the next candidate and drops every later candidate that shares the failed credential. The credential stays in the pool and is attempted again on the next invocation. A quoted error, or a line of tool output that reads like an authentication failure, reaches no further than this. That is what keeps a valid credential from being disabled by something the agent printed. Removal from rotation is the stronger one, and only the runtime's own terminal event earns it. Claude reports a rejected identity there as a structured HTTP 401 or 403. Codex sends no status at all and states it in that event's message instead — `Your access token could not be refreshed because your refresh token was already used. Please log out and sign in again.` — so Bento reads the message on that one field, and nowhere else. Bento then marks the credential dead: it leaves every queue and every target that names it, receives no probes, and stays dead across restarts. An interrupted or timed-out attempt never disables the credential, whatever its output says, because an abort proves nothing about the credential. For a Codex refresh-token rejection, sign in again and replace the configured credential with the new authentication data, then clear the dead credential as below. To bring one back, replace the secret, delete its row from the `credential_cooldowns` table, and restart the daemon. All three steps are needed: the pool reads that table once at startup and is authoritative from then on, and `credentials` is restart-required, so neither a replaced secret nor a deleted row reaches a running daemon. Leave the row alone and Bento drops it on the first restart more than 30 days after the failure, and the credential is attemptable again from then on. Knowledge rewrite uses an ordered target route. On quota or authentication failure, it tries the next candidate on each call and records no cooldown. Bento searches on the unrewritten prompt when the route gives no answer. A capability definition declares an optional ordered `targets` list. Without one, the capability inherits the parent invocation route. ## Orchestrator ```yaml orchestrator: targets: [claude-high, claude-backup] ``` Sets ordered target defaults for pipelines that explicitly declare `orchestrator.strategy.type: auto`. This block does not enable orchestration by itself. A pipeline that omits its own `orchestrator` field spawns its named agent directly. There is no built-in target default. An opted-in pipeline requires this block. The in-process orchestrator supports a target whose runtime is `claude`. Bento tries the fallback targets before it dispatches any specialist work, and they share the invocation timeout. The orchestrator target is independent of each pipeline's specialist targets. ## Host tools Host tools are daemon-host executables that the daemon exposes through MCP. Each tool is registered as `host_`: ```yaml host_tools: deploy_status: description: Check deploy status for a service input: service: { type: string, required: true } exec: ./scripts/deploy-status.sh args: ["--service", "$service"] ``` | Field | Description | |-------|-------------| | `description` | Tool title shown to the agent. | | `input` | Parameter map. Each entry has `type` (`string` | `number` | `boolean`), optional `required`, optional `default`. | | `exec` | Executable that runs on the daemon host with a 120 s timeout. Use an absolute path, `./` path, or `../` path. It takes no placeholder. | | `args` | Argument list. Each entry becomes exactly one argv element after `$name` substitution. | | `stdin` | Written to the process's stdin. Put structured input here. | | `env` | Extra environment variables for the process. Put secrets here. | The daemon starts the process directly. It does not use a shell. A value that contains `;`, `&&`, `|`, a backtick, `$(…)`, a quote, or a newline stays one argument. It never starts a second command. Bento does not support the `run:` shell template, and it rejects a config that contains one. Put the program in `exec`. Put each remaining word in one `args` entry. Bento also rejects `orchestrator.tools`. Move its definitions to `host_tools`. Do not put an input placeholder in the `PATH` value. Each host tool needs its own grant. To call `host_`, the token of the caller holds the scope `host:execute:` or the `*` wildcard. `mcp:write` does not authorize a host tool. The daemon refuses the token it issues to a sandboxed agent, whatever scopes that token carries. An agent inside a sandbox never runs a command on the daemon host. The daemon logs the token id, the tool, and the decision. It does not log argument values. *** ## Formatter ```yaml formatter: target: claude-high ``` Runs an optional model pass over structured `reply_body` output before posting it. Omit the block to post the extracted body unchanged. *** ## Ask ```yaml ask: targets: [claude-haiku-low, codex-low] ``` Sets the ordered target route used by `bento ask` invocations. The first name is the primary target. A quota or authentication failure advances to the next candidate. Any other failure stops the command and shows the error. Each target expands its own `credential_pool` in declaration order before the route moves to the next target, so a route can cross runtimes. The daemon refuses to start when this field is missing, when a name is not in `targets:`, or when a name repeats. Pass `--target` one or more times to replace the configured route for one invocation. The earlier scalar `ask.target` is refused. Replace it with a one-name route, `targets: [claude-high]`. | Field | Description | |-------|-------------| | `targets` | Ordered non-empty list of unique names from `targets:`. | *** ## Credentials ```yaml credentials: claude: max-0x: kind: subscription env: CLAUDE_CODE_OAUTH_TOKEN work: kind: subscription path: ${HOME}/.bento/provider-credentials/claude/work/.credentials.json claude-api: kind: api_key env: ANTHROPIC_API_KEY_WORK codex: oai-personal: kind: subscription path: ${HOME}/.codex/auth.json openai-api: kind: api_key env: OPENAI_API_KEY_WORK ``` Defines named model-provider accounts referenced by targets. Credential names are unique across runtimes. Secrets remain in environment variables or auth files. Configuration stores only their source names or paths. ### Configure subscription credentials To add separate work and personal Codex subscriptions, run these commands from the project directory: ```sh bento setup codex work bento setup codex personal ``` Complete each provider login. Bento stores the files under `~/.bento/provider-credentials/` and adds these entries to `.bento/daemon.yaml`: ```yaml credentials: codex: work: kind: subscription path: ${HOME}/.bento/provider-credentials/codex/work/auth.json personal: kind: subscription path: ${HOME}/.bento/provider-credentials/codex/personal/auth.json ``` To prefer work and use personal only after an authentication or quota failure, add the accounts to a target in that order: ```yaml targets: codex-high: runtime: codex model: gpt-5.6-sol credential_pool: [work, personal] ``` The setup command rejects an existing name before it opens the browser. To replace a named subscription, run `bento setup PROVIDER NAME --reauth`. Bento writes `${HOME}` in the configuration, so the configuration does not contain your home directory name. Restart the daemon after you add or replace a credential. | Runtime / kind | Source | Delivered as | |----------------|--------|--------------| | `claude` / `subscription` | `env` or `path` | `CLAUDE_CODE_OAUTH_TOKEN` or per-run `.credentials.json` | | `claude` / `api_key` | `env` | `ANTHROPIC_API_KEY` | | `codex` / `subscription` | `path` | Per-run `auth.json` in `CODEX_HOME` | | `codex` / `api_key` | `env` | `CODEX_API_KEY` for the `codex exec` invocation | | `pi` / `api_key` | `env` | `OPENROUTER_API_KEY` | | `pi-google` / `api_key` | `env` | `GEMINI_API_KEY` | | `opencode` / `api_key` | `env` | `OPENROUTER_API_KEY` | Every run receives only its selected provider credential. Bento removes every other native provider credential variable from that run's environment. Daytona receives path-backed Codex authentication through a per-run remote `CODEX_HOME`. The daemon does not mount the source file. `api` remains accepted as an alias for existing configurations. The registry is fixed at daemon startup. After editing it, run `bento config validate` and then `bento daemon restart`. *** ## Defaults ```yaml defaults: guardrails: timeout: 900 knowledge: method: none delivery: browse filter: tags: [conventions] sandbox: backend: docker setup: - run: ./scripts/index-symbols.sh ``` Global guardrails apply to every pipeline unless the pipeline overrides them. Fields merge by key. A pipeline's `guardrails:` block takes precedence where both set the same field. See [Pipeline guardrails](/pipelines/config#guardrails) for the field reference. `defaults.knowledge` works the same way for knowledge injection (`filter` replaces wholesale rather than merging). See [Pipeline knowledge](/pipelines/config#knowledge) for the `method`/`delivery` fields. `defaults.sandbox` and `defaults.setup` supply shareable defaults for pipelines on the same daemon. Terminal delivery is declared per pipeline with `result:` and `outputs:`; the legacy `output:` field is rejected. See [sandbox](/pipelines/config#sandbox), [setup](/pipelines/config#setup), and [terminal projections](/pipelines/config#terminal-projections) for the field references. `defaults.sandbox` is also where a daemon-wide [dependency cache](/pipelines/config#dependency-cache) belongs. The merge is per-key, so a pipeline that declares its own `cache` replaces the default list rather than adding to it. *** ## Queue ```yaml queue: host: concurrency: 2 remote: concurrency: 8 jitter: 10m retry: attempts: 3 circuit_breaker: failure_threshold: 5 stall_after: 15m cooldown: 5m escalate: webhook: https://ops.example.com/bento-alerts slack: { bot: alertBot, channel: C0123456789 } ``` Each queue lane has its own worker pool and concurrency limit: * `host.concurrency` limits runs on local backends, including Docker, Podman, and just-bash. * `remote.concurrency` limits Daytona and Cloudflare runs. Both pools share queue persistence and workspace serialization. A job does not wait for a worker slot on another lane. The circuit breaker pauses new runs after `failure_threshold` consecutive failures. Five outcomes do not count toward it: * An agent timeout. * A run drained on shutdown. * A checkout that lost its GitHub connection (`workspace_network_failed`). * A Cloudflare sandbox bridge request refused while it redeploys itself, or a running sandbox interrupted while the platform replaces its runtime (`workspace_network_failed`). The daemon grants the run one extra attempt before either counts as a failure. * A run that gave up waiting for a free snapshot slot (`snapshot_full`). Run `bento queue resume` to clear a trip by hand at any time. A tripped breaker also resumes itself after `cooldown` passes. The default `cooldown` is `5m`. Set it to a positive duration, such as `30s`, `5m`, `2h`, or `1d`. Set it to `never` to keep the breaker manual-only. A value the daemon cannot parse causes a startup error. The job the resumed queue claims first decides what happens next. A failure trips the breaker again at once, without waiting for `failure_threshold`. It also doubles `cooldown` for the next automatic resume, up to a cap of one hour. A success resets `cooldown` to the configured value, and so does a manual `bento queue resume`. The daemon sends an `escalate` message on every trip, including a re-trip. The message names when the queue resumes, or that it does not for `cooldown: never`. The pause and a doubled cooldown are kept in memory. A daemon restart clears both. `bento queue status` shows why a paused queue claims nothing. A circuit-breaker pause shows a countdown to its automatic resume, or `manual resume` for `cooldown: never`. It also shows the consecutive failure count and the most recent failure messages. A queue paused for another reason, such as a startup prerequisite the daemon has not satisfied yet, shows that reason instead. That reason never resumes on its own. The daemon also restarts itself when a queue lane stops starting jobs. A lane is unhealthy when its worker runner ended, or when the lane is stalled. A lane is stalled when these conditions stay true for longer than `stall_after`: the queue state is `running`, jobs on the lane are ready to run, and no job on the lane is active. A job that waits behind an active job in the same named queue is not ready to run. While a job on a lane is active, that lane is not stalled. The default `stall_after` is `15m`. Set it to a positive duration, such as `30s`, `5m`, `2h`, or `1d`. A value the daemon cannot parse causes a startup error. When a lane is unhealthy, the daemon sends one message to the `escalate` targets. The message names each unhealthy lane and the reason. Then the daemon waits until no job is active on any lane, so that the restart stops no run. At that time, the daemon drains and exits with code 1. A service manager that restarts on failure then starts the daemon again, for example `Restart=on-failure` in `bento.service`. If a job is still active one `stall_after` after the message, the daemon restarts and stops that job. The daemon does not restart while the queue is paused by the circuit breaker, or while the queue waits for its startup prerequisites. The sandbox backend selects the pool. Each pool defaults to 2 workers. Pipelines do not override pool selection or queue order. Jobs have equal priority and start in ready-time order, subject to workspace serialization. Remove `queue.fast` from daemon configuration and `lane` and `priority` from pipeline files before restart. Validation rejects these retired fields. At startup, the daemon moves pending fast jobs to host capacity and resets stored job priorities. It preserves job IDs, payloads, queue keys, attempts, and ready times, except for the effective lane. Historical traces retain their original lane labels. `jitter` spreads a burst of dispatches across a time window. Each dispatch in a burst waits for a random portion of the window before it becomes runnable. This spreads out starts, for example when a schedule labels many pull requests at once. Every dispatch still runs. Jitter does not increase throughput; `concurrency` controls it. A dispatch counts as part of a burst when the number of other dispatches enqueued on its lane in the previous 60 seconds reaches that lane's concurrency. This threshold uses `host.concurrency` or `remote.concurrency`. Below the threshold, the dispatch has no jitter delay. Only dispatches that create work count towards a burst. A repeat that replaces a pending job adds no load. A pipeline with a `debounce` combines its burst into one run and does not add jitter to its delay. Set `jitter` to a positive duration, such as `30s`, `5m`, `2h`, or `1d`. A value the daemon cannot parse causes a startup error. `circuit_breaker.escalate` tells the daemon where to announce a trip. The daemon sends the same message to each configured target when the breaker opens. Each target is independent. One target that fails does not stop the others, and a notification failure does not prevent the breaker from opening. `escalate.webhook` POSTs `{"message": "..."}` as JSON to the given URL. `escalate.slack` posts the message with `chat.postMessage`. Set both `bot` and `channel`. `bot` names an entry under [`channels.slack.bots`](#channels), which holds the token. `channel` is the id of the Slack channel to post into. A bot name on its own is refused when the config loads, because a bot entry holds no default channel. `escalate.telegram` is not implemented. A configured value writes a warning to the log and sends nothing. *** ## Workspaces ```yaml workspaces: checkoutRetentionDays: 30 transcriptRetentionDays: 90 closedRetentionDays: 14 ``` Retention tiers for stored workspaces. Once a workspace is idle past `checkoutRetentionDays` (default 30), the daemon reaps its regenerable `checkout/`. Run transcripts survive on the longer `transcriptRetentionDays` tier (default 90, clamped to at least `checkoutRetentionDays` so a transcript never expires before the checkout it describes). Notes are stored in the database and remain queryable beyond workspace retention. Independent of idleness, once a workspace's PR closes (stamped by the `system/workspace-closed` pipeline), the workspace files are removed `closedRetentionDays` (default 14) after the close. *** ## Triggers ```yaml triggers: retention: discardedDays: 14 completedDays: 90 ``` The `system/trigger-retention-sweep` pipeline removes expired trigger rows at 19:00 on weekdays, in the daemon's time zone: * Discarded rows expire after `discardedDays` (default 14). * Terminal rows (`done`, `error`, `timeout`, `superseded`) expire after `completedDays` (default 90). Discarded rows include unmatched webhooks and dispatches refused because a retry cannot change the outcome. Examples include a missing head ref at setup (`head_unchanged`), a workload lost to a restart (`workload_gone`), and an undiscovered agent or skill (`unknown_agent_reference`, `unknown_skill_reference`). Unknown agent and skill references indicate configuration drift that requires operator action. Increase `discardedDays` if you need more time to investigate them. These rows use the discarded retention window. To find them, use `--status discarded` or `--code `. The `bento trigger list --status error` command does not list them. The sweep never deletes a non-terminal row. Each retention value is a nonnegative number of days. An invalid value fails the sweep without deleting any rows. Rows retain their full payload until deletion, so a discarded trigger remains replayable with `bento trigger replay --ignore-filter` during its retention window. *** ## Tokens ```yaml tokens: retention: revokedDays: 30 ``` The bundled `system/revoked-token-sweep` action pipeline removes expired revoked token rows hourly. A revoked token keeps its row until the sweep removes it. The sweep prevents these rows from accumulating in the `tokens` table and `bento token list`. Revoked rows remain available for investigation for `revokedDays` (default 30) after revocation. The sweep never deletes active rows. Set a nonnegative number of days. An invalid value fails the sweep without deleting any rows. *** ## Repos ```yaml repos: my-project: url: acme/my-project branch: main pull_request_url: graphite sandbox: image: devcontainer ``` Repo entries used by schedule pipelines that require a checkout. Bento matches the `trigger.repo` field of a pipeline against the `url` of each entry (`owner/name`). The map key (`my-project`) is a label only, and bento never matches on it. `issue_tracker` names which tracker the repo's issues live on, surfaced through the `GET /repos` HTTP API. `github` is the only supported value, and is also the default when unset. `pull_request_url` sets where a message links this repo's pull requests, and overrides [`pull_requests.default`](#pull-requests). See that section for the values. `sandbox.image` sets the image the agent runs in for this repo, overriding the daemon default (`agent:default`). A pipeline's own [`sandbox.image`](/pipelines/config#sandbox) still wins over it. The value takes one of three forms: | Form | Example | Meaning | |------|---------|---------| | `devcontainer` | `devcontainer` | Use the repo's own `.devcontainer/devcontainer.json` (or root `.devcontainer.json`). The `image` field is used directly. `build.dockerfile` is built locally. Errors if the repo has none. | | `./` path | `./infra/Dockerfile`, `./svc/.devcontainer/` | Build from a repo-relative Dockerfile (its directory is the build context), or apply devcontainer semantics rooted at the named `.devcontainer/` directory. | | image reference | `ghcr.io/acme/dev:latest` | Use a prebuilt image as-is. | Repo-derived forms (`devcontainer`, `./` paths) resolve after the clone: setup runs in the default image, then the agent runs in the resolved one. They require a local container backend, Docker or Podman. On a remote backend such as Daytona, use an image reference instead. The image satisfies the agent-image contract (see `packages/images/agent-default/Dockerfile`). It ships the agent command-line interface the pipeline runs: `claude`, `codex`, `pi`, or `opencode`. Runs execute as `--user :0`, so it also declares an `ENV HOME` pointing at a group-0-writable directory (`chown -R 0:0 $HOME && chmod -R g=u $HOME`). Base custom images on `agent:default`, or replicate both in the Dockerfile. `sandbox.snapshot` declares a managed snapshot for the repo, in place of `sandbox.image`. A repo cannot set both. ```yaml repos: my-project: url: acme/my-project branch: main sandbox: backend: cloudflare snapshot: devcontainer: .devcontainer/agents.json env: [NPM_BUILD_CONFIG] runtimes: [claude, codex] refresh: 7d retain: 2 ``` Set `sandbox.backend` to `cloudflare` or `daytona`. Give exactly one of `dockerfile` and `devcontainer`, as a path inside the repository. Devcontainer builds require `cloudflare`. `ref` names the branch, tag, or commit to build and defaults to `branch`. `env` accepts the same entries as pipeline `env` (see [Environment](/pipelines/config#env)): a host variable name, a computed `command`, or a stored `secret`. Values are never stored in the declaration. `runtimes` lists the runtimes whose command-line interface must start in the image. Without it, every configured target applies. `refresh` is an interval such as `1d` or `12h`, with a minimum of `900s` and a default of `1d`. `retain` keeps 2 to 20 versions and defaults to 2. The daemon validates the declaration at boot and reports each problem with its key. The backend must be configured under `sandboxes`, and a Cloudflare declaration needs `cloudflare.accountId`. The `system/managed-snapshots` pipeline builds the snapshot on its next 15-minute pass, or now with `bento trigger schedule system/managed-snapshots`, under the alias `owner/repo:ref`, lower case, with `/` in `ref` replaced by `-` — the same alias a run derives automatically for that branch with no declaration, so both share one snapshot and its `max_concurrent` slots. See [Branch and commit tags](/cli/sandbox#branch-and-commit-tags) for that alias form, and for the one-release fallback to the pre-rename `owner/repo:repo-