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
- Console UI
- CLI
- Open Sandboxes in the Console and go to Images.
- Create a new image and give it a name.
- Set Type to Dev Image or Agent Image.
- Set Base to Standard base or Bring your own image. An agent image needs your own base.
- 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. - Set Image Tag (default
latest) and save.
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
createon 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
specrebuilds. So does changing acpln/tag such ascpln/restartedAt. - Deleting the
sandboximageobject 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.- Console UI
- CLI
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
pullon the image for you and mints a pull token scoped to that one repository, pull only and short-lived.--image-authsends your own token instead, which is normally unnecessary. A private image in any other registry takes animageAuthblock 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.
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.