Skip to main content
A sandbox image is an org-level resource that builds a dev sandbox image from a base image of your choice plus the fixed sandbox layer: the access and tooling layer every dev sandbox needs. Build it once, then select it as the container image of any dev sandbox. For the walkthrough see Build a sandbox image. The resource lives at /org/{org}/sandboximage/{name}. It is managed from the Console or the API; the cpln sandboximage command group covers it: create --name <n> [--base-image //image/<name>:<tag>] [--image-tag <tag>] [--type dev|agent] (an agent image needs --base-image), rebuild <ref...>, buildlog <ref> [-f] [--offset N], and get, delete, edit, update (--set accepts description, tags.<k>, spec.base.image, spec.tag, spec.type), patch, tag, clone, query, eventlog, audit, access-report, and permissions.

Sandbox image spec

The recipe has one tenant-controlled input: the base image to build FROM. There is no runtime, package, or install-command surface, so no arbitrary build shell runs under your org.

What the sandbox layer adds

The build takes your base (or the standard Ubuntu base) and layers the same components the standard dev image carries: Persistent install paths (~/.npm-global, ~/.local) are on PATH so packages you install inside the sandbox survive on the home volume.
If your base already has a uid 1000 user, it is renamed to devuser with its home moved to /home/devuser. Application code is not part of the image: clone repositories inside the running sandbox.

How a sandbox image build runs

  • Creating the object, or changing its recipe (spec, or a cpln/ tag such as cpln/restartedAt), submits a build to the platform build service under the caller’s own token. The caller needs image create in the org, the same right a registry push needs. Nothing holds the token past the call.
  • The built image lands in the org registry as an org image; status.imageLink points at it.
  • The build status is refreshed whenever the object is read.
  • The object’s event log at .../sandboximage/{name}/-eventlog records the build’s life: submission, queued, running, pushed or failed with the reason, and any failure to reach the build service.
  • The build output itself is at .../sandboximage/{name}/-buildlog; page through it with -buildlog?offset=N.
  • Delete answers 202 and leaves the built org image in place.
  • The org quota sandboximagesPerOrg caps how many sandbox images an org holds.

Sandbox image status

Sandbox image API examples

Create an image built on your own base:
Create an image on the standard base (no recipe):
Read it until the build is ready (the status refreshes on each read):
Tail the build output and the event log:
Rebuild without changing the recipe with cpln sandboximage rebuild python-tools, or by setting a cpln/restartedAt tag:

Using a sandbox image on a sandbox

Set the built image as the dev container image of a dev sandbox. In the Console, the Image field of the sandbox form lists Your Sandbox Images next to Standard. Through the CLI, pass the sandbox image link and the CLI resolves it to the built reference:
The CLI refuses --type worker, an agent-type image, an image whose build is not ready or has failed (follow it with cpln sandboximage buildlog python-tools -f), and a gvc-scoped link; any other --image value passes through. Through the API, or as the alternative on the CLI, pass the registry reference from status.imageRef:
A sandbox image carries the dev stack (gateway, IDE, terminal) and runs devboxd only to track activity. Dev-type images are for dev sandboxes; agent-type images are for sessions. An agent sandbox needs an image that runs devboxd on port 49983, such as build.cpln.io/public/agentbox-base:v1; see Sandbox. Sessions on an agent sandbox can run any OCI image of their own, which does not need the sandbox layer; see Sandbox sessions.