Skip to main content
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 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

Build a sandbox image

  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.
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

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. 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.
In the sandbox create form, set Image to one of Your Sandbox Images. The standard image is the other choice.

Per-session images for agents

An agent sandbox rarely needs a custom worker image. Each session can bring its own root filesystem instead:
  • 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 for the fields.

Next steps

Sandbox image reference

Every field of the sandboximage object and its status.

Work in a dev sandbox

Sign in, open the IDE, and connect a desktop editor.