The coding sandbox is an optional Cloudflare container that gives an Agent a real filesystem: a git checkout, package installs, test runs, and a dev server on a loopback port. Where a repository grant lets an Agent read code and open a pull request through the GitHub API, the coding sandbox lets it run the code. This page covers what the container adds, the two-part install handshake, how to verify it, the limits you can set, and how to remove it.
What it adds
The default Cloudflare deploy is the core deployment profile. It declares no Sandbox binding, builds no image, and creates no container application, which keeps first deploys small.
With the coding sandbox on, an Agent that holds a repository grant can clone that repository over plain HTTPS, install its dependencies with npm ci or pip install, create a branch, change several files, run npm test or pytest, and push the branch before opening a pull request. It can also start the repository’s dev server in the background, poll a loopback URL until it answers, and take a full-page Chromium screenshot that Chickpea posts back into the Slack thread.
Normal Slack replies, administration, GitHub browsing, and repository-aware model work do not depend on a container. Without the coding sandbox, every Agent uses the standard sandbox, an in-memory bash environment with no host filesystem and no host git or SSH access.
Prerequisites
- A Cloudflare account on Workers Paid. The container application and its Ubuntu-based image live in your Cloudflare account and may incur costs on it. Admin states the running cost as “a typical session costs about 1 cent”.
- The Owner or Admin role in Chickpea. Sandbox settings require the
admin.configurepermission, which Members do not hold. - The Chickpea GitHub App connected, and at least one repository granted to an Agent. Installation can start before these are done; runtime enablement cannot.
- Time for the first image build. Cloudflare builds and distributes the Ubuntu-based image before it can report ready, and that build takes several minutes.
No deploy-time secret is involved. CHICKPEA_DEPLOY_PROFILE is a non-secret build variable, not a runtime secret.
Install the container
Chickpea records your request but cannot redeploy itself, because deployment authority stays in your Cloudflare account. The install is therefore two parts: a request in Admin, then a redeploy in Cloudflare.
Request installation
In Settings → Coding sandbox, choose Install coding sandbox. Read the Workers Paid, build-time, and retained-infrastructure disclosure, then choose Request installation.
The status badge changes to Redeploy required.
Redeploy with the sandbox profile
Admin shows numbered steps for the way this installation is deployed, and you can switch between the two.
Deployed with a command (a local checkout, a release archive, or your own CI). From the checkout you install and update from, signed in to the same Cloudflare account, with Docker running (the deploy builds the sandbox image locally) and a Wrangler login that has the Containers permission (containers:write), run:
npm run deploy:sandboxIf you deploy with a named Wrangler login, pass it the same way: npm run deploy:sandbox -- --profile <name>.
Cloudflare Git builds (including Deploy to Cloudflare installs). In Cloudflare dashboard → Workers & Pages → your Worker → Settings → Builds, under Build variables and secrets, add the plain variable CHICKPEA_DEPLOY_PROFILE with the value sandbox. Then start a new build: push a commit, or retry the latest build from the Worker’s Deployments page. If the build finishes but Check again still shows Redeploy required, push a new commit so Cloudflare runs a fresh build.
The first image build takes several minutes.
Confirm the rollout in Cloudflare
Wait for the build to finish, then open Cloudflare dashboard → Containers → Container applications. Open this Worker’s Sandbox application and confirm that the latest rollout is ready.
Check again in Chickpea
Return to Settings → Coding sandbox and choose Check again. This reads the live deployment without changing your request. The status should become Installed but off.
If the page offers Connect GitHub or Manage repository access, complete that prerequisite first. Chickpea refuses enablement while either is missing.
Enable it
Choose Enable coding sandbox, tick I confirmed the Container application is ready, and enable. The checkbox is deliberate: the binding can exist while the first image rollout is still unavailable.
The status becomes On.
While a redeploy is outstanding, Cancel request clears the installation request and runtime enablement together, so a later redeploy cannot turn a canceled sandbox on. It changes nothing in Cloudflare.
Verify
In a channel where an Agent with a repository grant is published, start a new thread and ask it to clone the granted repository, install its dependencies, make a small change, run the tests, and report the result. Then ask the same Agent for a repository it was never granted, and confirm the request is refused.
Treat the clone and the dependency install as the load-bearing check, not a formality. Container egress is mediated by the Worker, so a passing install is your evidence that the mediated path covers the allowed lanes. Record that result.
Start a new thread for the test. The sandbox choice is made when a conversation begins and is not changed in the middle of an existing one.
What each status means
| Status | Meaning | Next action |
|---|---|---|
| Unsupported on Node | This target cannot install the Cloudflare container tier. | Use the standard sandbox, or deploy Chickpea to Cloudflare. |
| Not installed in this deployment | This is the core deployment profile and no install is pending. | Choose Install coding sandbox. |
| Redeploy required | The request is saved, but the live Worker has no Sandbox binding. | Redeploy with npm run deploy:sandbox or the build variable, then Check again. |
| Installed but off | The binding is live but runtime use is disabled. | Finish GitHub and grant setup, confirm the rollout, then enable. |
| On | Binding, stored runtime choice, GitHub App, and a repository grant are all ready. | Test a repository-backed request in Slack. |
| On, setup required | Runtime was enabled, but GitHub or repository access is now missing. | Follow the single prerequisite action shown. |
Errors and unchanged checks leave the last confirmed status on screen. Read the inline result before retrying; a button click is not proof that Cloudflare finished the deployment.
What is in the image
The image extends Cloudflare’s Sandbox SDK base at version 0.12.4, which supplies Ubuntu, Node 22.23.1, and git, curl, and jq. Chickpea adds Python 3 with pytest 8.3.4, and Playwright 1.49.1 with Chromium preinstalled so screenshots do not pay an install cost per turn. This vendor-owned container runtime runs sandbox tooling, independently of Chickpea’s Node 24 host/build policy. Keep its image tag matched to @cloudflare/sandbox and validate SDK/image upgrades separately. Project dependencies are not baked in; the Agent installs them after the clone.
Limits and settings
Advanced in Settings → Coding sandbox holds the two settings you can change, plus the fixed instance type.
| Limit | Value | Scope |
|---|---|---|
| Instance type | standard-1, read only |
Fixed by the sandbox deployment profile |
| Container instances | 25 | Per Worker |
| Monthly session cap | 200 recommended, 0 for no cap, 100000 maximum |
Per deployment, per UTC month |
| Idle sleep | 5 minutes | Per thread container |
| Allowed package hosts | registry.npmjs.org, pypi.org, files.pythonhosted.org |
Per deployment |
All three package hosts are permitted until you configure the setting, and the list accepts only those three. Saving an empty list blocks package installs. GitHub access does not come from this list: it comes from the Agent’s repository grants, and the credential is injected at the sandbox egress boundary, never written into a clone URL.
When the monthly cap is reached, a new coding session declines with “The coding workspace monthly session limit has been reached.” The Agent keeps working on read-only repository questions and small API-only changes. A retried turn reuses its reservation, so one turn cannot consume the cap twice. Counting rolls over at the start of the next UTC month.
The workspace disk is ephemeral. The container sleeps five minutes after the last operation and the disk goes with it, so a pushed branch is the durable checkpoint.
Sandbox egress denies workflow dispatch and deployment approval endpoints, including POST /repos/<owner>/<repo>/dispatches and workflow dispatch under /actions/workflows/. Public port exposure is not used: verification stays on loopback inside the container.
Disable, or remove it completely
Disable in Admin takes effect immediately. It stops selecting the coding sandbox for new work and deliberately leaves the container application and image in Cloudflare, where they may continue to incur costs.
To return to the core deployment profile and remove the retained resources:
- Choose Disable in Chickpea.
- Deploy the core profile, selecting it explicitly: the deploy refuses to remove a live sandbox by default. From your checkout, prefix your usual command, for example
CHICKPEA_DEPLOY_PROFILE=core npm run deploy -- --profile <name>. For Cloudflare Git builds, setCHICKPEA_DEPLOY_PROFILEtocoreunder Settings → Builds → Build variables and secrets and start a new build. - Verify ordinary Slack replies and Admin access on the core deployment.
- Delete the retained container application and image in Cloudflare.
Upgrading keeps whatever profile you select. Deploy with npm run deploy:sandbox, or keep CHICKPEA_DEPLOY_PROFILE=sandbox, to retain the binding across an update. Stored enablement has no effect without the binding, so a deployment that drops the variable needs the install again before it can be re-enabled.
On Node
Node deployments cannot install the coding sandbox. They use the standard sandbox, which never receives the host filesystem or host git and SSH access. The status reads Unsupported on Node and the settings offer no install action.
Next steps
- Agents: repository grants, skills, and the rest of what an Agent is made of.
- Deploy and operate: deployment profiles, upgrades, and what runs on each target.
- Security model: how credentials are resolved at egress and why conversation cannot expand authority.