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 taggedcpln/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 namesandboxesis held by a GVC placed elsewhere, the server usescpln-sandboxesinstead; when both names are held by GVCs placed elsewhere, every sandbox create fails with400until 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.sandboxto a workload in another GVC is refused the same way. - The
cpln sandboxandcpln sandboximagecommands find the org’s sandbox GVC themselves; do not pass--gvc. (A--gvcor 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.
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 setsspec.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.
spec.type other than stateful is rejected with a 400: a sandbox keeps a home volume, which only stateful workloads can mount.
- Console
- CLI
- API
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, sospec.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 aGET shows everything below.
Standard container
Whenspec.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.
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.autoscalingis pinned tominScale: 1,maxScale: 1, withscaleToZeroDelayfrom 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"]andoutboundAllowCIDR: ["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. AfirewallConfigyou 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 isstatus.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
scaleToZeroDelayseconds (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, andcpln port-forwardalso 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>setsspec.defaultOptions.suspend: true(andsuspend: trueon everyspec.localOptions[]entry), which stops compute untilcpln 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.
Updating and deleting a sandbox
- A sandbox stays a sandbox. Removing
spec.sandboxon aPUTfails withspec.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
PUTkeeps the stored parts. The stored token, container, and volume carry forward when the body omits them. volume.initialCapacityis immutable. A different value fails withspec.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.sandboxto 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 withvolumeset '<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 pastidleDeleteDelay, down tominWorkers. 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:
Sandbox spec examples
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.