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

# Build a sandbox image

> Supplement your own base image with the Control Plane sandbox layer, watch the build, and run dev sandboxes on the result. Also covers which images agent sandboxes and sessions can use.

A sandbox image is a `sandboximage` object that the platform build service builds under your token into your org registry. It has two types. A dev image (`spec.type: dev`, the default) is your base image plus the fixed sandbox layer: the user, SSH, browser IDE, terminal and CLIs that a [dev sandbox](https://docs.controlplane.com/guides/sandbox/dev-sandbox.md) needs. An agent image (`spec.type: agent`) is your base image copied alone into the org registry, for sessions on an agent sandbox.

## When you need a sandbox image

| Sandbox | What to run |
| :- | :- |
| Dev sandbox with the standard tools | Nothing to build. Omit the image; the server uses `build.cpln.io/public/sandbox-base:v1`. |
| Dev sandbox with your own toolchain | Build a dev image from your base image. The layer adds what the IDE, terminal and SSH access need. |
| Agent sandbox (`type: worker`; the reference says worker when it means the workload) | Any image that runs the agent API daemon, `devboxd`, on port 49983. The standard `build.cpln.io/public/agentbox-base:v1` is the usual choice. The standard dev image is refused for `type: worker` because it does not serve the daemon's API. |
| Code that agents run | Usually not a worker image at all: give each session its own image, public or an agent image you built. See [per-session images](#per-session-images-for-agents). |

## Build a sandbox image

> [tab] Console UI
>
> 1. Open **Sandboxes** in the Console and go to **Images**.
> 2. Create a new image and give it a name.
> 3. Set **Type** to **Dev Image** or **Agent Image**.
> 4. Set **Base** to **Standard base** or **Bring your own image**. An agent image needs your own base.
> 5. For your own base, set **Base Image** to an org image link such as `/org/my-org/image/base:latest`, or a full public reference.
> 6. Set **Image Tag** (default `latest`) and save.
>
> The build starts on save. The image's phase updates each time you open it.

> [tab] CLI
>
> ```bash theme={null}
> cpln sandboximage create --name py-dev --base-image //image/base:latest --image-tag v1 --org my-org
> cpln sandboximage create --name py-agent --type agent --base-image //image/agent-base:latest --org my-org
> cpln sandboximage buildlog py-dev -f --org my-org
> cpln sandboximage rebuild py-dev --org my-org
> cpln sandboximage get py-dev --org my-org
> cpln sandboximage delete py-dev --org my-org
> ```
>
> `--type` defaults to `dev`; `--base-image` is optional for a dev image (the standard base is used) and required for an agent image. `--image-tag` defaults to `latest`. `buildlog -f` follows the build output; `rebuild` submits the build again.

> [!NOTE]
>
> The `cpln sandbox` and `cpln sandboximage` commands on this page need a current `cpln` CLI. Run `cpln sandboximage --help` to see what your installed version supports. They find the org's sandbox GVC themselves; do not pass `--gvc`.

### Build phases

| `status.phase` | Meaning |
| :- | :- |
| `pending` | The build is being submitted. |
| `queued` | The build service accepted it and will start it. |
| `building` | Running. |
| `ready` | Done. `status.imageRef` is the full registry reference and `status.imageLink` the org image. |
| `failed` | `status.error` says why: the build service reply and step for a rejected submission, or the build log reason. |

The build's life is also written to the object's event log at `GET /org/{org}/sandboximage/{name}/-eventlog`. The build output itself is at `GET /org/{org}/sandboximage/{name}/-buildlog`.

### What the sandbox layer adds

The layer of a dev image is fixed; the base image is the only input. What it installs on top of your base is listed in [What the sandbox layer adds](https://docs.controlplane.com/reference/sandbox/image.md#what-the-sandbox-layer-adds). An agent image gets no layer: the base is copied as is.

On a sandbox's first boot the home volume is seeded from the image's `/home/devuser`, so files the base image puts there become the user's defaults.

### Constraints

* The build runs under **your** token. You need `create` on images in the org, the same right a registry push needs.
* Images must be `linux/amd64`.
* The only build input is the base image. To add tools, build them into the base image you point at; there is no package or command list.
* Changing `spec` rebuilds. So does changing a `cpln/` tag such as `cpln/restartedAt`.
* Deleting the `sandboximage` object leaves the built org image in place, listed under the org's images.

## Use the image on a sandbox

A dev image goes on a dev sandbox.

> [tab] Console UI
>
> In the sandbox create form, set **Image** to one of **Your Sandbox Images**. The standard image is the other choice.

> [tab] CLI
>
> ```bash theme={null}
> cpln sandbox create my-dev --image //sandboximage/py-dev --org my-org
> ```
>
> The CLI resolves a ready dev image to its built reference before the create; it refuses this form for `--type worker`, for an agent image, for an image whose build is not ready yet or failed (check with `cpln sandboximage buildlog py-dev -f`), and for a gvc-scoped link. Any other `--image` value, such as the reference in `status.imageRef`, passes through as given.

## Per-session images for agents

An [agent sandbox](https://docs.controlplane.com/guides/sandbox/agent-sandbox.md) rarely needs a custom worker image. Each session can bring its own root filesystem instead:

```bash theme={null}
cpln sandbox session create --sandbox my-agent --id task-1 --image node:22-slim --org my-org
```

* Public images are pulled anonymously, Docker Hub shorthand included.
* An agent image you built lands in the org registry like any other org image; the Console's **New Session** form offers it in its **Image** select.
* A private image in this org's registry needs no credentials from you: the server checks `pull` on the image for you and mints a pull token scoped to that one repository, pull only and short-lived. `--image-auth` sends your own token instead, which is normally unnecessary. A private image in any other registry takes an `imageAuth` block with basic credentials.
* The image must contain `/bin/sh`. Distroless images are refused. zstd-compressed layers are not supported.
* The image is unpacked once per digest and shared by every session that uses it; each session writes to its own layer.

See the [sessions reference](https://docs.controlplane.com/reference/sandbox/sessions.md) for the fields.

## Next steps

> [card] [Sandbox image reference](https://docs.controlplane.com/reference/sandbox/image.md)
>
> Every field of the sandboximage object and its status.

> [card] [Work in a dev sandbox](https://docs.controlplane.com/guides/sandbox/dev-sandbox.md)
>
> Sign in, open the IDE, and connect a desktop editor.
