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

# Sandboxes

The `bento sandbox` commands set up the remote sandbox providers and let an operator provision a snapshot by hand. Every snapshot command takes `--provider cloudflare` or `--provider daytona`. Cloudflare also has commands for the bridge, the Worker that runs sandboxes in Cloudflare Containers.

## Set up the Cloudflare bridge

### Before you begin

The bridge runs in Cloudflare Containers, which need the [Workers Paid plan](https://developers.cloudflare.com/containers/). Cloudflare Containers are not available on Workers Free, and the Workers subscription is separate from [Cloudflare website plans](https://developers.cloudflare.com/workers/platform/pricing/).

Complete these steps on the account that `cloudflare.accountId` names:

1. Activate Workers Paid for the account.
2. In the Cloudflare dashboard, confirm that you have access to **Workers & Pages > Containers**.
3. Set `cloudflare.accountId` in `.bento/daemon.yaml`.
4. Create an API token restricted to that account, and export it as `BENTO_CLOUDFLARE_API_TOKEN`. Grant Workers Scripts Edit, Containers Edit, and API Tokens Read. Optionally grant Workers Observability Read for startup diagnostics. For the metadata permission, select the Account category for an account-owned token, or the User category for a user-owned token. Setup rejects a token with extra permissions or a broad resource scope.
5. Install Docker and Wrangler on the deployment host, and start Docker.

If the account does not have Workers Paid, deployment fails with `Unauthorized` after the Worker upload and the local image build. If you see that error, check the plan and the token permissions.

### Deploy the bridge

```sh
bento sandbox setup --provider cloudflare
bento sandbox status --provider cloudflare
bento sandbox update --provider cloudflare --dry-run
bento sandbox update --provider cloudflare --yes
```

Setup deploys a Worker named `bento-sandbox-bridge`. To choose another name, pass `--name`. Setup does the following:

* Generates a bridge access key in the configured secret source.
* Writes `apiKeySecret` and the deployment identity into the configuration.
* Installs the account ID and a scoped provisioning token in the Worker.

Restart the daemon after setup or update.

### Check and update the bridge

The bridge has its own version, separate from the CLI version. The `status` command reports two values. `version` is the bridge version that this CLI installs. `deployed.version` is the bridge version that runs in the Worker.

`status` also reports `orphans`: registrations in the bridge that this daemon created and that the daemon has no record of. For example, a daemon that started with a new database leaves its earlier registrations behind. Each orphan still counts against the registration limit until it is removed. The report needs the daemon to be running. `bento doctor` warns when orphans exist.

To remove the orphans, run `bento sandbox snapshot prune --provider cloudflare --orphans`. The command lists the orphans and asks for confirmation. `--yes` removes them without a prompt. The daemon checks each registration again before it removes it. A registration that still has a running sandbox is reported as `busy` and is kept. A registration that Cloudflare is still removing is reported as `deleting`. Run the command again later to remove these.

The report assumes that one database holds all snapshot records for a daemon `name`. Do not connect two daemons with the same `name` but different databases to one bridge. Each daemon reports the registrations of the other daemon as orphans, and `prune` removes the idle ones.

The `update` command deploys the bridge version that this CLI installs. `--dry-run` reports the plan and deploys nothing. `--yes` approves the deployment without a prompt. An update keeps the bridge key, repairs missing provisioning bindings even at the same bridge version, and refuses to run while a sandbox is active.

`setup` and `update` build and push the container image first, then take a maintenance lock on the bridge, then deploy. The bridge refuses new sandboxes only from the start of the lock, not during the image build or push. A build or push that already ran skips its step and reports the skip. An early, advisory check for active sandboxes runs before the image build too, so a busy bridge fails fast; the authoritative check runs again just after the lock, since a sandbox can still start in between.

Progress prints to stderr, one line per step, with a heartbeat line if a step runs for longer than 30 seconds with nothing new to report. It prints only in a terminal; a piped or scripted run stays quiet unless you pass `--verbose`, which also prints raw build, push, and deploy output. `--format json` always prints the result to stdout, structured with what the run changed: the bridge and template versions before and after, the image build and push outcome, and how long the lock was held.

`setup`, `update`, and `destroy` all take the same maintenance lock — `destroy` holds it only around removing the Worker's containers and images, since that is the step that must not race a sandbox starting. Ctrl-C while any of the three holds the lock releases it before the CLI exits. The CLI also saves the lock to a local file while it holds it.

Before taking a new lock, `setup`, `update`, and `destroy` all first check for a lock file left by an earlier interrupted run, and release it. If that release fails, the command stops with an error naming the lock and when it expires, and keeps the file — the bridge lock is a singleton, so overwriting the file here would lose the only local copy of a still-held lock's id. Releasing the lock the command took itself works differently: a failure there is only a warning, and the run still succeeds; the file stays for a later run to find and clear. `bento sandbox status --provider cloudflare` reports a held lock, when the CLI took it, and when it expires.

### Read the bridge logs

The bridge sends its logs to Cloudflare Workers Logs. The logs include an invocation log for each request, the log lines that the Worker writes, errors, and uncaught exceptions. Use the logs to find the cause of a failed bridge request, such as a snapshot registration that returns HTTP 500.

To read the logs:

1. In the Cloudflare dashboard, go to **Workers & Pages**.
2. Select the bridge Worker.
3. Select **Observability**.

Workers Logs record every request to the bridge. The bridge configuration enables `observability` and does not set `head_sampling_rate`, so Cloudflare uses the default sampling rate of 1. Retention depends on the Workers plan. On Workers Paid, which the bridge requires, Cloudflare keeps logs for 7 days. The plan includes 20 million log events each month. Refer to [Workers Logs](https://developers.cloudflare.com/workers/observability/logs/workers-logs/) for the current limits and prices.

A bridge older than 1.1.0 does not send Workers Logs. To enable Workers Logs, update the bridge with `bento sandbox update --provider cloudflare`.

## Managed snapshots

A managed snapshot is an image that the daemon builds from a repository, verifies, refreshes on an interval, and retains in versions. An agent run starts from the snapshot instead of installing dependencies on every run. A snapshot has an alias of the form `ORGANIZATION/REPOSITORY:TAG`. The tag cannot contain `/`.

Declare the snapshot once per repository under `repos.<name>.sandbox.snapshot` in `.bento/daemon.yaml`. The daemon builds it on its next pass, refreshes it on the declared interval, and every pipeline on that repository runs on it unless the pipeline sets its own `sandbox.image` or `sandbox.snapshot`. See [Repos](/configuration#repos) for the declaration.

```yaml
repos:
  my-project:
    url: acme/my-project
    branch: main
    sandbox:
      backend: cloudflare
      resources:
        cpu: 4
        memory: 12GiB
      max_concurrent: 1
      snapshot:
        dockerfile: agent.Dockerfile
        refresh: 1d
        retain: 2
```

### Branch and commit tags

A declared repository's alias is `ORGANIZATION/REPOSITORY:REF` — the repository's `branch`, or `snapshot.ref` when set, with each `/` replaced by `-`. This is the same alias a run derives automatically for that branch with no declaration, so a declared snapshot and an undeclared run on the same branch share one snapshot and its `max_concurrent` slots, the way a Docker image tag such as `myapp:develop` names one moving target regardless of who pushed it.

A tag of 7 to 40 hexadecimal characters, such as `ORGANIZATION/REPOSITORY:6d6b5c30e`, names a commit prefix instead of a branch. It pins the ready version whose revision starts with that prefix, never the newest, and counts against the same `max_concurrent` limit as the branch alias, so a commit-pinned run and a branch-tracking run compete for the same slots. Two ready versions matching the prefix are ambiguous; supply a longer prefix. No version matching the prefix reports the same not-ready diagnostic as an empty branch alias.

An alias always pins its newest ready version, whether a declaration or `bento sandbox snapshot create` built it. A manual build under a declared alias does not disable the declaration or block its rebuild schedule: it wins admission until the declaration's next build lands, then the declaration's build wins again.

Before this alias form, a declared alias was `ORGANIZATION/REPOSITORY:repo-LABEL`, prefixed with the `repos.<name>` key to avoid colliding with the automatic branch alias. While a daemon has not yet built under the new alias — for one release after upgrading — a run pins the newest ready version under the old alias instead, so runs keep working through the first build. Trigger that first build with `bento trigger schedule system/managed-snapshots`, or wait for the declared `refresh` interval. After the new alias has a ready version, the next pass prunes the versions under the old alias that no run uses.

`resources` sets minimum CPU, memory, and optional disk capacity for the repository snapshot. Memory and disk accept numbers in GiB or strings with `MiB`, `GiB`, `MB`, or `GB` units. Cloudflare selects the smallest instance type that meets all requirements and rejects unsupported requests. Daytona rounds requirements up to whole CPUs and GiB. Without `resources`, the existing backend defaults apply.

`max_concurrent` limits active invocations across versions of the same snapshot alias. Each run reserves a slot before it starts and holds it until its trigger finishes. A trigger that matches several pipelines starts one run for each pipeline, so it reserves one slot for each run. While the snapshot is full, the run waits in the queue. A finished invocation's sandbox slot expires 10 minutes after it completes if no close was recorded. Bento checks again every 15 to 30 seconds, for up to 30 minutes. After 30 minutes, the trigger fails with `snapshot_full`, and the run does not start. Queued runs do not start in arrival order. A direct invocation with no reservation is refused until a slot becomes free. Cloudflare also receives this value as its per-version instance limit. A change to `max_concurrent` alone resizes that limit on the running Cloudflare instances. The daemon does not rebuild the image for this change. A declaration that drops `max_concurrent` resizes Cloudflare back to its own default limit, the same way. Update the managed bridge before using these fields with Cloudflare. If the bridge does not support them, the snapshot fails before the build starts. A bridge older than 1.4.0 does not resize in place. The daemon logs a warning and leaves the registered limit unchanged until you update the bridge.

The Cloudflare bridge also refuses sandbox creation immediately when a snapshot version reaches its instance limit. This returns HTTP `429` with `snapshot_full`, without the 30-minute alias queue wait. Check the diagnostic message to distinguish this bridge refusal from an exhausted alias queue wait.

The snapshot commands on this page are the manual path. Use them for a repository that has no declaration, for a build outside the interval, or to inspect what the daemon holds.

### Provision a snapshot by hand

Before you create a snapshot, authenticate `gh` for the repository, and give the daemon host the provider credentials and build tools. Cloudflare needs `BENTO_CLOUDFLARE_API_TOKEN` and Docker. Daytona needs `DAYTONA_API_KEY`.

```sh
bento sandbox snapshot create ORGANIZATION/REPOSITORY:main \
  --provider cloudflare \
  --ref feature/my-branch \
  --dockerfile agent.Dockerfile \
  --retain 2
bento sandbox snapshot list --provider cloudflare
```

The command queues a background build and returns. A snapshot created this way has no declaration. The daemon refreshes it on its own `--refresh-seconds` interval and never adopts it for a declared alias. The following options shape the snapshot:

| Option | Meaning |
| --- | --- |
| `--ref` | The branch, tag, or commit to build. Use it for a branch that contains `/`, because the tag cannot. |
| `--dockerfile` | The Dockerfile to build, relative to the repository root. Defaults to `agent.Dockerfile`. |
| `--devcontainer` | A devcontainer configuration to build instead of a Dockerfile. See [Build from a devcontainer](#build-from-a-devcontainer). |
| `--refresh-seconds` | The refresh interval. Defaults to one day, with a minimum of 900 seconds. |
| `--retain` | The number of versions to keep per alias. Defaults to 2, and accepts 2 to 20. |
| `--runtimes` | The agent runtimes that the runtime checks require. See [Runtime checks](#runtime-checks). |
| `--compute-class` | A Daytona compute class from the configured classes. |
| `--cpu`, `--memory`, `--disk` | The minimum vCPUs, memory in GiB, and disk in GiB, as for `resources` in a declaration. Set `--cpu` and `--memory` together. `--disk` is optional. Without these options, the Daytona compute class or the backend default sets the size. |
| `--max-concurrent` | The limit on active runs across the versions of the alias, as for `max_concurrent` in a declaration. |

If a build for the same alias is queued, building, or provisioning, `create` returns that build and ignores the new options. Wait for the build to finish, then run `create` again.

### Refresh and retention

The `system/managed-snapshots` pipeline runs every 15 minutes. Each pass builds every queued snapshot, refreshes each snapshot whose interval has passed, and prunes old versions. To run a pass now, use `bento trigger schedule system/managed-snapshots`. The daemon logs each build step, from the repository clone through the image push.

A Cloudflare build starts only when the bridge reports the `processes` capability. Bridge 2.0 reports it, and bridge 1.x does not. If the daemon runs with bridge 1.x, or the daemon cannot read the bridge version, each pass keeps the Cloudflare builds in the queue and logs that the build waits for `bento sandbox update --provider cloudflare`. After you update the daemon, run that command to deploy bridge 2.0. The next pass then builds the queued snapshots.

Bridge 2.0 cannot run a version that bridge 1.x built, because that image has the earlier wrapper. The daemon queues one new build of the newest version of each Cloudflare alias that has the earlier wrapper. The bridge refuses a sandbox from an earlier version until retention removes that version. See [How the image runs on Cloudflare](#how-the-image-runs-on-cloudflare).

After Bento registers a Cloudflare image, Cloudflare must start an instance of it. A large image can take several minutes. While Bento waits, the build has the status `provisioning`, and each later pass checks it. The build becomes ready when one instance is healthy and the runtime checks pass. If an instance fails, or no instance starts within 60 minutes, the build fails. The previous ready version stays in use while the build waits.

Bento keeps `--retain` versions per alias and does not prune a version that a run uses. A declaration's versions keep this retention only while a declaration produces their alias. If no declaration produces the alias, for example after `ref` changes, the next pass prunes each of those versions that no run uses. Versions from `create` keep their retention. Cloudflare has eight registrations shared across all repositories, so retention on one repository can limit another. When all registrations are in use, a Cloudflare build stays queued until a later pass finds a free one. A registration that Cloudflare is still deleting still counts until the deletion completes. A version is not deleted while a sandbox made from it still exists: the Cloudflare bridge refuses the deletion, and on Daytona the daemon checks for such a sandbox first. Maintenance reports that prune as failed, and a later pass retries it.

### Retry a failed build

A failed build does not replace the ready version. The daemon builds a failed declared snapshot again after one hour, or after its `refresh` interval if that interval is shorter. It builds a failed snapshot from `create` again after its `--refresh-seconds` interval. Before that time, a pass does not build the snapshot, and `bento trigger schedule system/managed-snapshots` does not change this.

After you correct the cause of the failure, use `retry` to queue a new build now:

```sh
bento sandbox snapshot retry ORGANIZATION/REPOSITORY:main --provider cloudflare
bento trigger schedule system/managed-snapshots
```

`retry` accepts an alias or the ID of a build from `snapshot list`. For a declared alias, it retries the newest build of the declaration. For an alias without a declaration, it retries the newest build of the alias. For a build ID, it retries the newest build of the same alias that has the same `origin`. For a Daytona alias in a compute class that is not the default, add `--compute-class`.

The new build uses the options of the failed build. It also keeps its `origin`: `config` for a declared snapshot, `manual` for a snapshot from `create`. The failed build stays in `snapshot list` with its error and its timestamps. The next pass builds the new build. If the new build fails, the usual interval starts again from that failure.

The command reports one of these results:

| `result` | Meaning |
| --- | --- |
| `queued` | The daemon queued a new build. `build` is the new build. |
| `already_active` | A build of the alias is queued, building, or provisioning. `build` is that build. The daemon does not queue another build. |
| `skipped` | The newest build is ready, so there is nothing to retry. `nextEligibleAt` is the end of its refresh interval. |

If no build of the provider matches the alias or the ID, the command fails with HTTP 404. A build ID from a provider configuration that the daemon no longer uses does not match.

### Runtime checks

Before a snapshot becomes ready, Bento starts a container from the image and runs these checks:

* The home directory and `/workspace` exist and are writable.
* The workspace tools `bash`, `git`, `flock`, and `tar` are present.
* Git is version 2.41 or later.
* The command-line interface of each required agent runtime starts with `--version`.

For a Cloudflare build, the checks run twice: with Docker on the daemon host before the upload, and in a disposable Cloudflare sandbox after registration. The daemon host must run `linux/amd64` images. For a Daytona build, the checks run in a disposable Daytona sandbox. A failed check records the failure on the snapshot and keeps the previous ready version in use.

Cloudflare verification allows up to ten minutes for setup. Allocation failures retry the file upload on the same sandbox before command execution; commands are never replayed. Normal pipelines use the same retry path within their setup deadline. Maintenance reports an error if a build or prune operation fails; an image upload alone does not make a snapshot ready.

By default, the checks require the runtime of every target in `daemon.yaml`. When you add a target, the next build of every snapshot that uses the default requires its runtime too. An image without that runtime fails each refresh until you add the runtime to the image or pin the list. To pin the list for one snapshot, pass `--runtimes` with a runtime name from `targets.*.runtime`, once per runtime. The snapshot stores the list, every refresh uses it, and a later target change does not change it.

```sh
bento sandbox snapshot create ORGANIZATION/REPOSITORY:main \
  --provider cloudflare \
  --runtimes claude --runtimes codex
```

`--runtimes` also works with `snapshot build`, where only the Cloudflare local check uses it.

### Select a snapshot in a pipeline

To run a pipeline on a snapshot, set `sandbox.snapshot: ORGANIZATION/REPOSITORY:main` in the pipeline. The next run selects the newest ready version. A commit-prefix tag, such as `ORGANIZATION/REPOSITORY:6d6b5c30e`, pins that exact version instead — see [Branch and commit tags](#branch-and-commit-tags). Without `sandbox.snapshot`, Bento derives an alias from the repository and the branch, with each `/` in the branch replaced by `-`. If a ready snapshot exists under that alias, the run uses it. Set `sandbox.snapshot: none` to run on no snapshot, even on a repository that declares one.

## Build an image only

To publish an image without managed refresh or retention, use `build`:

```sh
bento sandbox snapshot build \
  --provider daytona \
  --repo ORGANIZATION/REPOSITORY \
  --ref main
```

Both `build` and `create` use the repository's `agent.Dockerfile` by default. If the file has another path, pass `--dockerfile`. Cloudflare reads the account from `cloudflare.accountId`, so there is no `--account` option. A build resolves the Git reference to a commit before it publishes. Cloudflare publishes an immutable image digest. Daytona publishes a private snapshot.

For a Daytona build, `--cpu`, `--memory`, and `--disk` select the resources. The defaults are 2 virtual CPUs, 4 GiB of memory, and 10 GiB of disk.

## Build from a devcontainer

A snapshot has one build source: `--dockerfile` or `--devcontainer`. Dockerfile builds support Cloudflare and Daytona. Devcontainer builds support Cloudflare only.

```sh
bento sandbox snapshot create ORGANIZATION/REPOSITORY:devcontainer \
  --provider cloudflare \
  --ref develop \
  --devcontainer .devcontainer/devcontainer.json \
  --retain 2
```

The same option works with `snapshot build`. Do not pass both build-source options. If you pass neither, Bento uses `agent.Dockerfile`. A devcontainer snapshot does not support Daytona or a Docker Compose configuration.

### Install the Dev Container CLI

Install the [Dev Container CLI](https://github.com/devcontainers/cli) on the build host so that `devcontainer` is on the daemon's `PATH`. Bento tests this path with Dev Container CLI 0.89.0. Docker must be running. Repository authentication, Cloudflare credentials, refresh, registration, and retention work the same as for a Dockerfile snapshot.

### What the build does

Bento builds the pinned repository revision with `devcontainer build --platform linux/amd64`. The Dev Container CLI resolves the configuration and installs features. Configuration files, Dockerfiles, build contexts, and repository symlinks must stay inside the checkout. Build only a repository that you trust, because Dockerfile steps and feature installers run code on the build host's Docker engine.

The build creates an image, not a running development environment. Bento does not run these lifecycle commands during snapshot creation:

* `initializeCommand`
* `onCreateCommand`
* `updateContentCommand`
* `postCreateCommand`
* `postStartCommand`
* `postAttachCommand`

Bento does not copy a bind-mounted workspace into the image. If the snapshot needs source files, installed dependencies, or generated clients, put those steps in the devcontainer's Dockerfile.

### Use a private registry

For a private dependency, use a Docker BuildKit secret mount. In the devcontainer build options, reference an environment variable by name:

```json
{
  "build": {
    "dockerfile": "Dockerfile",
    "context": "..",
    "options": ["--secret", "id=npmrc,env=NPM_BUILD_CONFIG"]
  }
}
```

Consume it in the Dockerfile:

```dockerfile
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc,required=true pnpm install --frozen-lockfile
```

Supply `NPM_BUILD_CONFIG` to the daemon process through your secret manager, then grant it on the snapshot request:

```sh
bento sandbox snapshot create ORGANIZATION/REPOSITORY:devcontainer \
  --provider cloudflare \
  --ref develop \
  --devcontainer .devcontainer/devcontainer.json \
  --env NPM_BUILD_CONFIG
```

`--env` also works with `snapshot build`. For variable-name entries, the request stores only the names, and the build reads the values from the build host at build time. A granted variable that is not set fails the build. The Dev Container CLI receives the standard process and Docker connection settings plus the explicit grants, and nothing else. A repository that names another daemon variable does not gain access to it.

For managed snapshots, `repos.<name>.sandbox.snapshot.env` accepts the same entries as pipeline `env`: a variable name, a host command, or a stored secret. For example:

```yaml
snapshot:
  devcontainer: .devcontainer/agents.json
  env:
    - name: PLATFORM_BUILD_NPMRC
      command: bun scripts/snapshot-npmrc.ts
      required: true
```

Commands run on the build host in the pinned repository checkout, with a 60-second timeout. Only configure commands from trusted snapshot refs: they run with the host's credentials. Trimmed stdout becomes the value, including internal newlines. Omit `ttl` to mint a fresh value for each build; `ttl` caches it in memory for that many seconds, separately from pipeline values. A required command or secret failure stops the build. The snapshot record stores the declaration, not the resolved value. `snapshot.build_env` and the CLI `--build-env` option were replaced by `env` and `--env`. Rename existing string lists; the values do not change.

Docker mounts a granted value for the build step only. Do not copy the mount or print its contents. Do not pass a credential through a build argument, a Dockerfile `ENV`, or a devcontainer `${localEnv:...}` substitution. Those mechanisms can persist the value in image metadata or layers. Registry authentication remains the responsibility of the configured command or secret source.

In the repository's `build.options`, Bento accepts only `--secret id=ID,env=GRANTED_VARIABLE`, with an optional `type=env`. Bento rejects a file-based secret, SSH forwarding, an output directory, an additional build context, and every other raw build flag.

### How the image runs on Cloudflare

The Cloudflare wrapper adds `/usr/local/bin/sandbox-shim` from `cloudflare/sandbox:1.0.0` to the image. The bridge runs each sandbox command through `sandbox-shim`. The wrapper sets a shell init as the entrypoint, and the init is the main process of the container. The init starts the feature entrypoint hooks, then the image's original entrypoint and command, in the background. The init stays alive after that command exits, so a long-running command is not necessary. The init also removes ended orphan processes, keeps the image environment for each sandbox command, and stops on SIGTERM.

The earlier wrapper ran a `/sandbox` server, which bridge 2.0 does not use. A version with the earlier wrapper does not run on bridge 2.0, so the daemon builds the newest version of each alias again. See [Refresh and retention](#refresh-and-retention).

The wrapper does not replay runtime-only settings: desktop mounts, port forwarding, `runArgs`, `remoteUser`, and environment overrides. Docker-outside-of-Docker needs a host socket that Cloudflare does not provide. If a sandbox needs Docker, select a separate Cloudflare devcontainer configuration that starts Docker inside the sandbox. Bento does not replace Docker features for you.

A successful image build does not prove that Cloudflare supports the image's runtime requirements. Verify a sandbox run before you use the snapshot in a pipeline.
