Skip to main content
A session is an isolated slot on an agent sandbox (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.
For the daemon’s own HTTP API (processes, files, PTY, previews), see the Agent API reference. For the sandbox fields of the workload, see the sandbox reference.

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 require view 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, with identity 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 with image:
  • 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 install lands 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 example PATH and PYTHON_VERSION) becomes the session’s default environment. The session workspace is bound in at its usual path, and the worker’s /etc/resolv.conf and /etc/hosts are lent read-only so installs resolve.
  • The image must contain /bin/sh; distroless images are refused with 424. 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.
An image in the org registry needs no credentials from you. When 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.maxSessions sessions (default 20, at most 500; injected as DEVBOXD_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 answers 429 with Retry-After: 15 and worker 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 429 with Retry-After: 15 and worker is full: <n> MB free, the session needs <m> MB (<k> sessions on the box). limits.memoryMb above the worker’s usable memory answers 422. A create without limits.memoryMb needs DEVBOXD_SESSION_MEMORY_RESERVE_MB (default 256) free, and DEVBOXD_MEMORY_RESERVE_MB (default 128) is kept back for the worker itself.
Memory limits behave differently per runtime:
  • 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 answers 409 with session container is stopped: the sandbox exited (under gVisor a memory limit ends the whole session); create a new session.
Size gVisor limits for the whole task, or use runc where a runaway process must not end the session.

Session response fields

A successful create answers 201 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 the runtime 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.com gives a session the same allow and refuse behavior. A session created through the GVC route with its own firewall runs 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:
  1. Mint one with POST .../-sessions/{id}/-preview-code (needs connect on the worker) or, with the sandbox or session token, POST /_api/sessions/{id}/preview-code on the worker. The answer is { "code": "…", "param": "preview_code", "expiresInSeconds": 60 }.
  2. 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.
A session holds at most 8 unspent codes; minting a ninth answers 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):
A deleted session’s log is still readable by id. The same id created again starts a fresh log. Caps, per worker, set as environment variables on the worker container: 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).
The worker’s own CPU counts too: work outside any session (an agent or a build started from a shell) holds the worker up the same way. Box-level reads (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

  1. 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.
  2. 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.
  3. When every worker is full, the server adds one: <identity>-<n> (or sandbox-<n> for the pool without an identity), cloned from the pool’s template worker and tagged cpln/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 and use on the identity; otherwise the create answers 403. Long identity names get a hash tail so the worker name fits.
  4. 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 answers 429 with Retry-After: 15 and worker <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.
  5. When the pool already has maxWorkers members and all are full, the create answers 429 with Retry-After: 30.
The server also creates the next plain worker ahead of demand, off the request, when the chosen worker was the last one with room or the pool is under minWorkers.

Placement of a session with its own firewall

A session created with a firewall 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 tagged cpln/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

The cpln 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:
Create a session for an identity through the GVC route, waiting up to 60 seconds for a booting worker:
Read the last 100 stdout lines of a session by its id:
Mint a one-time code and open the session’s port 3000 in a browser:
Send SIGTERM to a process in a session, then delete the session: