maxSessions (default 20), and only while its memory has room. When your agents need more, stop naming a sandbox and name an identity instead. The platform puts each session on a sandbox of that identity with room, adds sandboxes when all are full, and removes the ones it added once they sit empty. You change one line in your orchestrator.
This page assumes you know how a single agent sandbox works. An agent sandbox is type: worker; the reference says worker when it means the workload. The identity, the sandboxes, and the route all belong to the org’s sandbox GVC.
The
cpln sandbox commands on this page need a current cpln CLI. Run cpln sandbox --help to see what your installed version supports. They find the org’s sandbox GVC themselves; do not pass --gvc.Create sessions by identity
Create the identity in the sandbox GVC if it does not exist, then create sessions for it. You do not need to create a sandbox first: the first session for an identity with none gets one.- Console UI
- CLI
Open Agent Sessions, choose New Session, pick the Identity, and leave Agent sandbox on Let the platform choose.
worker (the sandbox that holds it) and endpoint. The server appends -<key> to your id, 9 characters: a dash and 8 hex characters that name the sandbox:
identity in the body (see the sessions reference). An id you choose may be at most 55 characters, since the server appends the key.
Tune the pool
The sandboxes of one identity form a pool, and the first sandbox in it is the template the server clones for the rest. Create that one yourself to choose its size, image, firewall, and scaling; otherwise the server’s first one runs the standard image at 4 CPU and 8 GiB with the default scaling.spec.sandbox.scaling fields, with their ranges and defaults, are in the Scaling section of the sandbox reference: maxSessions is enforced by every sandbox, pool or not; minWorkers, maxWorkers, and idleDeleteDelay only matter on the template. scaling is for agent sandboxes; a dev sandbox is one box and rejects it.
Handle a full pool
When no sandbox can take the session right now, the create answers429 with a Retry-After header. Wait that long and send the same create again; the orchestrator example in the Agent API reference already does this.
The API gateway does not replay a
429, so the retry is the client’s.
Watch the pool
- Console UI
- CLI
Agent Sessions is this list, filtered by identity if you like. Its Active tab reads the platform’s records and wakes nothing; Ended and All probe every sandbox and wake the scaled-to-zero ones.
id, worker, endpoint, runtime, image, created, active, lastActive) and every sandbox of the identity:
With
probe=true on the API route each sandbox answers for itself: ready, unreachable, or deploying, its full session list, whether it has room, and a capacity block with its memory.
How it works
Placement ranks the sandboxes of the identity you may use (connect) without calling any, calls only the top-ranked one to confirm room, and when every one is full adds bot-<n> as a clone of the template, tagged cpln/sandbox-pool=bot; the steps are in How a GVC session create is placed. A reconciler on the server deletes a server-added sandbox that has sat empty longer than idleDeleteDelay, down to minWorkers, adds one when the pool is short, and never deletes a sandbox you created; see Worker reconciliation.
A session created with its own firewall (--set firewall.external.outboundAllowHostname=...) lands on a sandbox pinned to exactly those rules, tagged cpln/sandbox-firewall, created on first use and never ahead of demand. Such sandboxes are excluded from plain placement, count toward maxWorkers but not minWorkers, and are removed when idle regardless of minWorkers.
Each sandbox scales to zero on its own once its sessions go idle, after its scaleToZeroDelay. Placement prefers ready sandboxes, so a wake is paid only when nothing else has room. The counts the server uses are the gauges each sandbox exports (devboxd_active_sessions, devboxd_idle_since_seconds, and per session devboxd_session_active), scraped into the org’s metrics.
Next steps
Sessions reference
The GVC and workload session routes, placement rules and every error code.
Sandbox reference
Every field of spec.sandbox, including scaling.