The
cpln sandbox commands on this page need a current cpln CLI (cpln sandbox --help shows what yours supports); they find the org’s sandbox GVC themselves, so do not pass --gvc.Create an agent sandbox
- Console UI
- CLI
Open Sandboxes, start a new sandbox, pick Agent Sandbox, adjust CPU and memory if the 4 CPU and 8 GiB default does not fit, and create. See Sandboxes in the Console.
maxSessions of them (default 20). When either runs out, the next session is refused until one ends; when you need more, scale by identity.
Get the endpoint and token
Your agent needs two things: the sandbox’s endpoint and its token.- Console UI
- CLI
On the Overview, choose API on the agent sandbox’s row. The Endpoint and Token card shows the endpoint and the token; Connect From Your Terminal shows the first commands to run against it.
Give an agent a task
A task is: open a session, put the inputs in, run the command, take the outputs out, close the session. Here it is end to end.- Console UI
- CLI
Open Agent Sessions, choose New Session, pick the sandbox, set an image, and create. The session’s page has a Connect tab with the API calls that drive it filled in, a Processes tab, and its logs.
cpln sandbox session processes task-1 --sandbox my-agent lists what is still going, and cpln sandbox session signal task-1 --sandbox my-agent --process <pid> stops it (SIGTERM by default; --signal SIGKILL to force).
Pick what the task runs in
On the CLI these are
--image, --runtime, --memory, --port, --log, --env, and --user; in the Console they are the fields of New Session. A private image in the org registry is pulled with a token scoped to it: the server checks pull on the image and mints a short-lived pull token for that one repository. Pass --image-auth (imageAuth in the sessions reference) only to send your own token instead.
Open a shell in a session
For a look around, or to let a person drive what the agent set up:bash when the session’s image has it, sh otherwise. For a single command, use cpln sandbox session exec.
Preview a port
A session that serves a port, say a dev server on 3000, has its own URL. Each session has its own port space, so two sessions can both use 3000.- Console UI
- CLI
The session’s Preview tab opens a declared port, or any port you type, and mints the code for you.
preview: public (--preview public); that link does not expire.
See what happened
- Console UI
- CLI
Agent Sessions lists every session with its status (Running, Idle, Paused while its sandbox is scaled to zero, Starting, Ended), sandbox, runtime, and image. Open one for its processes, log with filters, and CPU, memory, and disk charts. Ended sessions stay listed, with their logs and metrics readable even after the sandbox is gone.
--log it also holds the processes’ output. The log outlives the session, up to 7 days or the sandbox’s caps. Metrics are sampled every 5 seconds and kept the same way.
Clean up
Drive it from your own code
Everything above is an HTTP call: the platform’s-sessions routes under the org’s sandbox GVC create and list sessions with your Control Plane token, and the sandbox’s own API runs commands, moves files, and serves previews with the session token. The Agent API reference documents the routes and ends with a complete Python orchestrator that creates a session per task, streams a command’s output, collects the result, retries when the sandbox is full, and deletes the session. The sessions reference has every create field and error code. The sandbox GVC is tagged cpln/sandboxGvc: default in orgs created with the built-in default GVC, otherwise sandboxes, created with your first sandbox; GET /org/{org}/gvc/-sandbox names it.
Lock down what agents can reach
The sandbox’s firewall applies to every session’s traffic, and a sandbox defaults to open in both directions. When agents must only reach specific hosts, restrict the sandbox:Lock down egress per session
When one task needs its own rules, set them on the session through the GVC route (by identity, not--sandbox):
maxWorkers, not minWorkers, and are removed when idle. --set firewall={} closes egress entirely.
To give agents a secret or private network access, assign an identity of the org’s sandbox GVC with spec.identityLink and reference the secret in the container’s environment (cpln://secret/<name>). Every command in every session sees those values, so do this only when the agents need it. The same mechanism lets the agent loop itself run inside a sandbox: give the runner sandbox an identity that can reveal the model API key, start the loop in a session with the Control Plane token it needs as an envs entry, and poll its results with /_files.
How it works
Sessions and isolation
Sessions and isolation
Every sandbox is its own Firecracker microVM, which is the boundary between tenants. Inside one agent sandbox, each session is a nested OCI container with its own workspace, network namespace, and address.
runc shares the kernel with the sandbox at near-native speed; runsc (gVisor) gives each session a user-space kernel, the strongest isolation inside one VM. A requested runtime is never downgraded: 422 if the sandbox lacks it, 424 if it could not start.Per-session images
Per-session images
An image is pulled straight from its registry, flattened once per digest into a store on the sandbox, and mounted read-only under a writable layer for each session. A
pip install lands in the session, never in the store, and the next session on the same image skips the pull. The image must contain /bin/sh; distroless images are refused with 424, and zstd-compressed layers are not supported. Commands run as the image’s root unless you pass a numeric user.Why cpln workload exec does not work here
Why cpln workload exec does not work here
The sandbox runs privileged inside its microVM so it can nest containers, and it owns the cgroup tree to enforce session limits. The platform’s exec path cannot attach to it. Use
cpln sandbox session exec, cpln sandbox session connect, or POST /_api/process/start without a session for a command on the box itself.When the sandbox scales to zero
When the sandbox scales to zero
The sandbox watches its sessions. One is active while it has a running process, an attached client, a request in the last 10 seconds, or real CPU use; work on the box outside any session counts too. Listing sessions, health checks, and reading logs never count. Once everything is idle, the sandbox suspends after
scaleToZeroDelay (default 300 seconds) and the next call wakes it; sessions and workspaces are still there, and the Console shows them as Paused meanwhile.Next steps
Scale by identity
Spread sessions of one identity across several sandboxes that the server adds and removes with demand.
Sessions reference
Every session field, response, placement rule and error code.
Agent API reference
Every route for processes, PTYs, files and previews.
Sandbox images
Build a custom image or use per-session images.