---
title: "Coding sandbox"
description: "Install the optional Cloudflare container that gives an Agent a real checkout, package installs, tests, and a dev server."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.chickpea.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Coding sandbox

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.configure` permission, 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.

1. **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**.
2. **Add the build variable and redeploy**

   In **Cloudflare dashboard → Workers & Pages → your Worker → Settings → Builds → Variables**, add the non-secret build variable `CHICKPEA_DEPLOY_PROFILE` with the value `sandbox`, then choose **Retry deployment**.

   If Retry reuses the earlier core artifact, start a fresh dashboard build instead. A completed retry is not proof that the new deployment profile was selected. From a local machine or CI, select the same profile with:

```sh
npm run deploy:sandbox
```
3. **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.
4. **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.
5. **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.

## 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. | Add the build variable, redeploy, 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:

1. Choose **Disable** in Chickpea.
2. Remove `CHICKPEA_DEPLOY_PROFILE` from **Settings → Builds → Variables**.
3. Retry the deployment, or run `npm run deploy`, to deploy the core deployment profile.
4. Verify ordinary Slack replies and Admin access on the core deployment.
5. Delete the retained container application and image in Cloudflare.

> **Caution**
>
> Do not delete the container application or image before step 4 passes. Deleting while a live Worker may still reference the container removes your rollback.

Upgrading keeps whatever profile you select. 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](/agents): repository grants, skills, and the rest of what an Agent is made of.
- [Deploy and operate](/operate): deployment profiles, upgrades, and what runs on each target.
- [Security model](/security/security-model): how credentials are resolved at egress and why conversation cannot expand authority.

Source: https://docs.chickpea.co/agents/coding-sandbox/index.mdx