Skip to main content
A sandbox is a stateful workload that carries a spec.sandbox section. The section marks the workload as a sandbox and holds its settings; the server fills in everything else: the container, the home volume, the ports, the probes, the firewall, and the tags. Two types exist: Both types keep a home volume at /home/devuser, run as a single replica inside a Firecracker microVM, scale to zero when idle, and resume on the next request. For the model behind the two types see the sandbox concept; for step-by-step instructions see Getting started with sandboxes.

The sandbox GVC

Every sandbox in an org lives in the org’s sandbox GVC: one GVC tagged cpln/sandboxGvc: "true" and placed on the single location that runs the sandbox microVMs (currently oci-us-ashburn-1). Which GVC that is depends on the org:
  • An org created with the built-in default GVC uses default.
  • An older org uses sandboxes. You do not create that GVC: the server creates it, as you, with the org’s first sandbox. If the name sandboxes is held by a GVC placed elsewhere, the server uses cpln-sandboxes instead; when both names are held by GVCs placed elsewhere, every sandbox create fails with 400 until one of them is placed on the sandbox location.
GET /org/{org}/gvc/-sandbox answers { "name": "<sandbox-gvc>", "location": "oci-us-ashburn-1", "exists": true | false }. The routes on these pages write that name as gvc/<sandbox-gvc>. From then on:
  • A sandbox created under any other GVC is refused with 400: Sandboxes are created in the '<sandbox-gvc>' GVC, placed on oci-us-ashburn-1 where they run: create this one under /org/<org>/gvc/<sandbox-gvc>/workload.
  • Adding spec.sandbox to a workload in another GVC is refused the same way.
  • The cpln sandbox and cpln sandboximage commands find the org’s sandbox GVC themselves; do not pass --gvc. (A --gvc or a profile default GVC is used as given.)
  • Identities a sandbox runs as, and the identity pools of agent sandboxes, are identities of the sandbox GVC.
Creating the first sandbox needs create on GVCs in the org in addition to the workload permissions. When the caller lacks it, the create fails with the GVC’s refusal and the hint An org admin can create GVC '<sandbox-gvc>' placed on oci-us-ashburn-1 only.

Sandbox creation in one call

The smallest valid sandbox is a workload whose spec contains only the section. The server sets spec.type to stateful when it is omitted, injects the standard container for the type, creates the home volumeset, and (for a worker) generates the token.
A spec.type other than stateful is rejected with a 400: a sandbox keeps a home volume, which only stateful workloads can mount.
Open Sandboxes in the org navigation, start a new sandbox, pick Dev Sandbox or Agent Sandbox, and create. The GVC field shows the sandbox GVC and cannot be changed. Every other field has a default. See Sandboxes in the Console.

Sandbox spec fields

Every field has a default, so spec.sandbox: {} is a complete sandbox.

Scaling

spec.sandbox.scaling is read on an agent sandbox (type: worker). maxSessions is enforced by the worker itself, so it matters even for a single agent sandbox. The other three fields describe the pool: the workers of the sandbox GVC bound to the same identity (or to none) share its sessions and scaling. The first worker of a pool is its template: the server clones it for the next ones. Session placement across workers is described in Sessions and Scale agent sandboxes by identity. A maxWorkers below minWorkers is rejected with spec.sandbox.scaling.maxWorkers must be at least minWorkers. Set the fields with cpln sandbox update <ref> --set spec.sandbox.scaling.maxSessions=50 (and the same for minWorkers, maxWorkers, idleDeleteDelay), or at create with --max-sessions, --min-workers, --max-workers, and --idle-delete-delay. A worker the server created for sessions that carry their own firewall (tag cpln/sandbox-firewall) is deleted when idle regardless of minWorkers; see session placement.

What the server injects into a sandbox

The section is normalized into the workload spec at write time. The stored spec round-trips unchanged, so a GET shows everything below.

Standard container

When spec.containers is omitted, the server injects one container named dev: A container you supply keeps its image, but a missing cpu or memory is filled with the type’s standard size above, not the platform’s 50m / 128Mi. Size the sandbox on spec.containers[0].cpu and memory. A worker is sized for the sessions it holds: they share its memory, and the daemon admits a session only while there is headroom.
A worker needs an image that runs devboxd on port 49983. The standard dev image does not, so a worker on build.cpln.io/public/sandbox-base:v1 is refused:
Images must be linux/amd64.

Ports, environment, and probes

The default probe uses initialDelaySeconds: 1, periodSeconds: 5, failureThreshold: 20, successThreshold: 1, timeoutSeconds: 1. You may replace it.

Home volume

The server creates and owns a volumeset named <workload>-state (performanceClass: shared, fileSystemType: shared, size from volume.initialCapacity) and mounts it on the dev container at /home/devuser with recoveryPolicy: retain. The volumeset is tagged with the owning workload link and is deleted with the sandbox. If a volumeset named <workload>-state already exists and is not this sandbox’s, the create fails with 409: volumeset '<name>' already exists. A sandbox creates and owns its home volumeset under this name (<workload>-state): delete or rename that volumeset, or pick another sandbox name.

Autoscaling and firewall

  • spec.defaultOptions.autoscaling is pinned to minScale: 1, maxScale: 1, with scaleToZeroDelay from the section. A sandbox is one replica with one home volume.
  • When the caller sets no firewallConfig, the server sets one that is open in both directions: inboundAllowCIDR: ["0.0.0.0/0"] and outboundAllowCIDR: ["0.0.0.0/0"], with the other allow and blocked lists set empty. Access is gated by the sign-in (dev) or the token (worker), not by the firewall. A firewallConfig you supply is kept as is.
This differs from the firewall default of an ordinary workload, which is closed. Restrict outboundAllowHostname or outboundAllowCIDR on a worker when its agents must reach only known hosts; sessions inherit the worker’s egress policy. A session created through the GVC route can carry its own firewall instead and lands on a worker pinned to those rules; see Session create fields.

Tags the server stamps

Do not set these tags yourself; the server maintains them. They count toward the 50-tag limit per object.

Reserved ports, env names, and paths

Endpoints by sandbox type

The URL is status.endpoint of the workload. What it serves depends on the type. The daemon’s own listener ports are never proxyable through /_port.

Sandbox access and permissions

Grant connect with a policy on the workload, as you would for cpln workload exec.

Scale to zero, wake, and suspend

Every sandbox runs as a Firecracker microVM that suspends in place when idle and resumes on demand. The home volume stays mounted; the next request continues where the box left off.
  • A sandbox is idle when no request has arrived on a declared port for scaleToZeroDelay seconds (default 300) and nothing inside it is working. Work means a running session process or CPU use above a small threshold: a build or an agent you left running in a dev sandbox terminal keeps the box up; an open but idle editor does not. On a worker, see session activity.
  • The next request to the endpoint wakes the sandbox. On a dev sandbox, cpln sandbox connect, cpln workload exec, and cpln port-forward also wake it before connecting. On a worker, a session create or any API call wakes it.
  • An idle sandbox reports the state suspended (scaled to zero; the Console shows Scaled to Zero).
  • Suspend is explicit: cpln sandbox stop <ref> sets spec.defaultOptions.suspend: true (and suspend: true on every spec.localOptions[] entry), which stops compute until cpln sandbox start <ref> clears it. The Console labels these Suspend and Unsuspend and shows a stopped sandbox as Suspended. A stopped sandbox does not wake on a request. The home volume is preserved either way.
Use automatic scale to zero for day-to-day idle time and an explicit suspend for a sandbox you will not touch for a while.

Updating and deleting a sandbox

  • A sandbox stays a sandbox. Removing spec.sandbox on a PUT fails with spec.sandbox cannot be removed: a sandbox is not converted back into a plain workload. Delete the sandbox instead; its home volumeset is deleted with it.
  • A minimal PUT keeps the stored parts. The stored token, container, and volume carry forward when the body omits them.
  • volume.initialCapacity is immutable. A different value fails with spec.sandbox.volume.initialCapacity is the initial size and cannot be changed (it is 20 GB). Resize the home volumeset '<name>-state' instead. Resize the volumeset itself.
  • Adding spec.sandbox to an existing stateful workload in the sandbox GVC creates its home volumeset.
  • Delete removes both objects. Deleting the sandbox deletes <name>-state. If another workload also mounts that volumeset, the delete fails with volumeset '<name>-state' is the sandbox's home volume but is also mounted by another workload; unmount it there first or delete that workload.
  • Workers in a pool. Server-added workers (tag cpln/sandbox-pool) are deleted by the server when idle past idleDeleteDelay, down to minWorkers. A worker you created is never deleted by the server.

Exec into a sandbox

cpln workload exec works on a dev sandbox. It does not work on an agent sandbox: the worker delegates its cgroup tree to session limits, so the platform cannot attach an exec process. Run commands on a worker through a session instead:
See Run agents in an agent sandbox.

Sandbox spec examples

Assign spec.identityLink only when the sandbox needs it: secret access, cloud access, private network access, or to join an identity’s worker pool. The identity must belong to the sandbox GVC.