Skip to main content
One agent sandbox holds a bounded number of sessions: at most 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.
Open Agent Sessions, choose New Session, pick the Identity, and leave Agent sandbox on Let the platform choose.
The response is the session plus 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:
Because the id names its sandbox, every later call can go through the GVC route without naming one:
From your own code the change is the same: create through the GVC route with 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.
The four 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.
Sandboxes are added under your permissions, as if you had created the workload. You need create on workloads in the sandbox GVC and use on the identity; otherwise the session create fails with 403 naming the sandbox it could not create.

Handle a full pool

When no sandbox can take the session right now, the create answers 429 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

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.
The list carries every session (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.