type: worker; this page says “worker” when it quotes the spec value or the API’s worker objects). Each session runs in its own nested OCI container with its own workspace, its own access token, and its own network namespace. The agent sandbox paid the boot cost once; creating a session on a running worker takes well under a second, so a session is the unit an AI agent creates per task or per conversation.
Sessions are created and managed through the platform API’s -sessions routes, which proxy to the agent API daemon, devboxd, on the worker using the sandbox token stored in spec.sandbox.token. Clients never need the sandbox token to use these routes; they authenticate with their Control Plane token. The routes are also what cpln sandbox session and the Console use.
The
cpln sandbox session commands on this page need a current cpln CLI. Run cpln sandbox session --help to see which commands your installed version supports.Session API routes
All routes live under the org’s sandbox GVC, written<sandbox-gvc> below; GET /org/{org}/gvc/-sandbox returns its name (see the sandbox GVC). A -sessions route on a workload that is not an agent sandbox answers 400 (not an agent sandbox).
Routes on one agent sandbox
These routes address a specific worker by its workload name. Reads requireview on the workload; writes require connect.
Routes across the sandbox GVC
These routes span every agent sandbox in the sandbox GVC. A session created here is placed on a worker by identity (see Placement and scaling). The session id returned ends in-<8 hex>, a key derived from the worker’s name, so later calls by id find the worker without a lookup.
Every session answer, on either route family, carries two platform-added fields:
worker (the workload holding the session) and endpoint (that worker’s https endpoint). Clients that talk to the Agent API directly use endpoint.
A session’s own token is included in answers only when the caller holds connect on the worker. A caller with only view sees the session without the token and without its envs.
Session create fields
The create body is passed through to the daemon, withidentity consumed by the GVC route. Every field is optional; an empty body {} creates a session on the worker’s own root filesystem with the default runtime.
Session images
A session may bring its own root filesystem withimage:
- The daemon pulls the image straight from its registry. Public images pull anonymously; Docker Hub shorthand (
node:22-slim) is accepted; an image index is resolved for the worker’s platform (linux/amd64). - The image is flattened once per manifest digest under the worker’s image store and mounted read-only as the lower layer of the session’s root filesystem, with a per-session writable upper layer. A
pip installlands in the session, never in the shared store, and a second session on the same image skips the pull. - The store is a bounded cache: 30% of the worker’s disk, or
DEVBOXD_IMAGE_CACHE_MB. The least recently used image is evicted first, never an image a running session uses. - The image’s config
Env(for examplePATHandPYTHON_VERSION) becomes the session’s default environment. The session workspace is bound in at its usual path, and the worker’s/etc/resolv.confand/etc/hostsare lent read-only so installs resolve. - The image must contain
/bin/sh; distroless images are refused with424. Layers compressed with zstd are not supported. - An image session needs a container runtime; on a worker that is not privileged the create answers
422.
image names one, as a registry reference (<org>.registry.cpln.io/<name>:<tag>) or as an image link (//image/<name> or /org/<org>/image/<name>), and the body carries no imageAuth, the server checks that the caller holds pull on that image, mints a pull token scoped to that one repository, pull only and short-lived, and hands it to the worker for the pull. A caller without pull gets 403 Image <name> cannot be pulled: pull is not granted on it; a caller the server cannot identify gets 401. The Console describes such an image as pulled with a token scoped to it.
imageAuth is the override: credentials you supply for the pull of a private image. It is used once and never stored on the session, written to disk, or logged.
imageAuth without an image is a 400. Using kind: cpln for a registry other than the org’s is refused before anything is pulled.
Session admission and memory limits
A worker admits a session on two counts:- Session count. A worker holds at most
spec.sandbox.scaling.maxSessionssessions (default 20, at most 500; injected asDEVBOXD_MAX_SESSIONS), and has 254 session network slots (one network namespace each), so the count stays below that. At the limit a create on that worker answers429withRetry-After: 15andworker is full: <n> sessions on the box, the limit is <n>. Through the GVC route the session lands on another worker instead. - Memory headroom. Sessions share the worker’s memory. When the worker does not have enough free memory for the session’s limit, the create answers
429withRetry-After: 15andworker is full: <n> MB free, the session needs <m> MB (<k> sessions on the box).limits.memoryMbabove the worker’s usable memory answers422. A create withoutlimits.memoryMbneedsDEVBOXD_SESSION_MEMORY_RESERVE_MB(default 256) free, andDEVBOXD_MEMORY_RESERVE_MB(default 128) is kept back for the worker itself.
- Under
runc, the kernel kills the process that exceeded the limit and the session lives on. - Under
runsc(gVisor), the whole session is one host process, so exceeding the limit ends the session. Its next exec answers409withsession container is stopped: the sandbox exited (under gVisor a memory limit ends the whole session); create a new session.
runc where a runaway process must not end the session.
Session response fields
A successful create answers201 with the session. The token is returned only here.
A list (
GET .../-sessions) returns the same per-session fields without token, plus state (the container state, for example running or stopped), created, procCount, mechanism, and the activity verdict active with lastActive. The list also carries a capacity block for the worker:
With
?include=ended, the list adds ended[], read from the session logs kept on the worker: id, created, ended, endReason, runtime, isolation, image, network, ip, preview, logOutput, and logBytes. Sessions a crashed or restarted daemon left open are listed as ended with the reason daemon restarted.
Session runtimes and isolation
Tenants are isolated from each other by the microVM: every sandbox is its own Firecracker guest. Inside one agent sandbox, sessions are isolated from each other by a nested OCI container, and theruntime field picks which one:
gVisor pays a tax on syscall-, fork-, and small-file-heavy work (package installs, builds) and is near parity for compute- and LLM-bound agents.
Both runtimes need the worker to run privileged inside its microVM. The
worker type stamps the cpln/kataPrivileged tag for this; without it the daemon reports isolation tier user and refuses named runtimes with 422. The price of a privileged worker is that cpln workload exec does not work on it (the daemon owns the cgroup tree). Run commands through sessions instead: cpln sandbox session exec, cpln sandbox session connect, or the Agent API.
An interactive shell in a session (cpln sandbox session connect, or a PTY started without a command) is bash when the session’s image has it and sh otherwise, started as an interactive shell rather than a login shell so the image’s own PATH stands.
Session networking and previews
A container-tier session gets its own network namespace: a veth pair into the worker, one/30 out of the session range (default 10.200.0.0/16, set by DEVBOXD_SESSION_NET on the worker), and a default route through the worker. Consequences: A worker has 254 of these session network slots, which is the practical ceiling below maxSessions.
- Every session has its own port space. Two sessions can both serve
:3000. - The worker’s firewall applies to session egress exactly as to the worker’s own traffic: a worker allowing only
api.github.comgives a session the same allow and refuse behavior. A session created through the GVC route with its ownfirewallruns on a worker pinned to those rules instead; see Session create fields and Placement. - DNS inside a session goes through a relay on the session’s gateway address.
- Sessions cannot reach the worker’s own listeners or one another.
Preview URLs
Any port a session serves is reachable on the worker’s endpoint at/_s/<session id>/<port>/.... This is the per-session counterpart of the box-wide /_port/<n>/ route: an agent can run a dev server on :3000 in every session and each gets a working URL. Declared ports are echoed back as ready-made URLs in preview.urls; undeclared ports route too.
Access is chosen per session at create with preview:
A browser cannot send a header, so it opens a
token preview with a one-time code:
- Mint one with
POST .../-sessions/{id}/-preview-code(needsconnecton the worker) or, with the sandbox or session token,POST /_api/sessions/{id}/preview-codeon the worker. The answer is{ "code": "…", "param": "preview_code", "expiresInSeconds": 60 }. - Open
https://<endpoint>/_s/<id>/<port>/?preview_code=<code>within 60 seconds. The daemon sets a cookie scoped to/_s/<id>/, spends the code, and redirects to the same URL without it, so WebSocket upgrades and later requests ride the cookie.
429 until one is opened or expires. cpln sandbox session preview <id> and the Console’s preview opener do all of this for you. A token placed in the URL (?access_token=) is refused with 401, because URLs are logged.
Session logs
Every session keeps a log on the worker’s home volume under/home/devuser/.devboxd/sessions/<id>/. The log outlives the session and the daemon and goes away with the worker. The log root is root-only and masked inside every session, so no session can read another’s log.
Query parameters on
-logs (and on the daemon’s GET /_api/sessions/{id}/logs):
DEVBOXD_SESSION_LOG_MAX_MB (default 50) per session, past which one log cap reached line is written and further lines drop; DEVBOXD_SESSION_LOG_TOTAL_MB (default 2048) over all ended sessions, oldest ended pruned first; DEVBOXD_SESSION_LOG_RETAIN_DAYS (default 7) after a session ends. Live sessions are never pruned.
Session metrics
The daemon samples each session’s cgroup every 5 seconds into a series kept beside the session log, under the same caps, and surviving the session.GET .../-sessions/{id}/-metrics?since=&until=&points= answers:
cpuPct is the share of the session’s allotted cores used since the previous point (100 = every allotted core busy); cpuUsec is the cumulative counter. points downsamples the window to at most that many points (default 300, at most 2000). points defaults to 300 and is capped at 2000.
The latest samples are also exposed in Prometheus text on the worker’s port 49984 at /metrics. The standard worker container declares that port as its metrics port, so the series land in the org’s metrics: per-session CPU seconds and share, memory with limit and cache, disk, processes, start time, deadline (devboxd_session_expires_at_seconds), and activity (devboxd_session_active, devboxd_session_last_active_seconds), plus the worker gauges devboxd_active_sessions, devboxd_box_active, and devboxd_idle_since_seconds. The Console reads these series for a session’s charts, so they stay readable after the session, and the worker, are gone. A session with a deadline also exposes devboxd_session_expires_at_seconds.
Sessions and scale to zero
An agent sandbox scales to zero like every sandbox (see scale to zero), and the daemon decides when the worker has work. A session is active while it has:- a running process started through the process API (an idle dev server counts, for as long as it lives),
- a client attached to one of its processes,
- a request addressed to it in the last 10 seconds, or
- CPU use in its cgroup of at least 2 percent of a core over the last sample (0.1 s per 5 s).
GET /_api/sessions, /_health, /metrics, logs, metrics) never count. Reads addressed to a session (process lists, file reads, watches) keep the worker up, so a console polling them holds it, but are not the session’s own use.
While anything is active, the daemon holds a lock on /home/devuser/.devboxd/activity.lock on the home volume, which blocks the platform from suspending the microVM. Once the last session goes idle, the lock is released and the worker suspends after the sandbox’s scaleToZeroDelay; its state is then suspended (scaled to zero; the Console shows Scaled to Zero). The next request to the endpoint, including a session create or a placement probe, wakes it; the sessions and their workspaces are still there. Sessions cannot reach the lock file.
The verdict is visible in the capacity block of a session list (activeSessions, boxActive, idle, idleSince), per session as active and lastActive, and as the gauges above.
Session placement and scaling
The agent sandboxes of the sandbox GVC that are bound to the same identity (spec.identityLink), or bound to none, form a pool. A session created through the GVC route names the pool with identity (or omits it for the pool without an identity) and the server picks the worker. You do not need to create a worker first: an identity with no worker yet gets <identity>-1 on the standard worker image at the standard size.
How many sessions one worker holds and how many workers the server keeps for an identity is set by spec.sandbox.scaling on the worker (maxSessions, minWorkers, maxWorkers, idleDeleteDelay); the fields, ranges, and defaults are in Scaling. The first worker of a pool is its template: the server clones it for the next ones.
How a GVC session create is placed
- The pool’s members the caller may use (
connect) are ranked without calling any of them, from deployment status and the daemon’s scraped gauges: workers with a known session count and room, ready before suspended (a wake costs time), fewest sessions first. - Only the chosen worker is called. A call wakes a suspended worker. If it reports room, the session is created there. Workers whose gauges are unknown (new, or just woken) and then suspended workers with unknown counts are tried next.
- When every worker is full, the server adds one:
<identity>-<n>(orsandbox-<n>for the pool without an identity), cloned from the pool’s template worker and taggedcpln/sandbox-pool=<identity | sandbox>. The worker is created through the public API under the caller’s permissions, so the caller needs workload create in the sandbox GVC anduseon the identity; otherwise the create answers403. Long identity names get a hash tail so the worker name fits. - The create waits for the new (or already booting) worker to answer with room, up to
?wait=<seconds>(at most 90, which is also the default), then answers429withRetry-After: 15andworker <name> is starting or has no room yet; retry shortly. Clients retry after the header’s delay. A worker that has stayed without an endpoint for 15 minutes is no longer waited for. - When the pool already has
maxWorkersmembers and all are full, the create answers429withRetry-After: 30.
minWorkers.
Placement of a session with its own firewall
A session created with afirewall is placed only on a worker pinned to the same rules: the worker’s firewall fingerprint must match the session’s. Pinned workers carry the tag cpln/sandbox-firewall and are excluded from the plain placement above. When no pinned worker with room exists, the server adds one on first use, cloned from the pool’s template with the session’s rules as its firewallConfig. Pinned workers count toward maxWorkers but not minWorkers, are never created ahead of demand, and are deleted when idle regardless of minWorkers.
Worker reconciliation
A reconciler runs every 60 seconds across the sandbox GVC of every org. It deletes server-added workers (those taggedcpln/sandbox-pool) that have been empty for longer than idleDeleteDelay, down to minWorkers, and creates workers up to minWorkers when the pool is short. The minWorkers floor counts plain workers only; an idle pinned firewall worker is deleted regardless of it. It never deletes a worker the user created, never calls a worker (a call would wake it), and never writes to a worker (a write would roll its pod). Idle time comes from the deployment status and the daemon’s last idleSince sample.
Worker state in a GVC list
GET .../gvc/<sandbox-gvc>/-sessions without probe=true lists every worker and its sessions with what is known without calling it:
With
probe=true, every worker is called: state is ready, unreachable (it has an endpoint but did not answer), or deploying (no endpoint yet), and a ready worker carries room and capacity.
Session error codes
The daemon deliberately answers
422 and 424 rather than 503 for a runtime that is missing or failed, because the platform’s gateway retries 503 responses, including POSTs, and would eventually replace the daemon’s message with its own.
Sessions CLI
Thecpln sandbox session commands wrap the routes above. The session id is the argument of every command, and --sandbox <ref> names the agent sandbox; leave --sandbox out to use the GVC route (with --identity on create to pick the pool). The commands find the org’s sandbox GVC themselves; do not pass --gvc.
Session API examples
Create a session on a named agent sandbox:SIGTERM to a process in a session, then delete the session: