worker) runs the agent API daemon, devboxd, as its only process on port 49983. That port is the workload’s one listener, so the workload endpoint (the status.endpoint value on the workload) is the API itself. There is no IDE, no terminal page, and no sign-in on an agent sandbox: the sandbox token gates everything.
This page documents that API. Most clients do not need the sandbox token at all: the platform’s -sessions routes and the cpln sandbox commands proxy session lifecycle, logs, metrics, processes, signals, and preview codes with the caller’s Control Plane token. The daemon API is for the agent loop itself: running commands, streaming output, moving files, and opening previews, at the worker’s endpoint and with the session or sandbox token.
Agent API authentication
Every request carries a token in theX-Access-Token header. Two kinds of token exist:
A token that matches nothing is
401. Comparisons are constant-time. Every route also accepts the token as Authorization: Bearer. Routes that take a browser (previews and the port proxy) also accept it as a cookie, and set that cookie from a one-time code; see Previews. A token in a URL (?access_token=) is refused with 401, because URLs end up in logs.
Three routes carry no auth: /_health (readiness; answers with X-Devboxd-Version and X-Devboxd-Commit headers), /_metrics (JSON cpu, memory, and disk of the worker), and the Prometheus exposition on the separate metrics port 49984 at /metrics, which only the platform’s in-cluster scraper reaches.
Session scoping of Agent API routes
Every process, PTY, filesystem, and archive route accepts an optionalsession=<id>: as a query parameter everywhere, and additionally as a "session" field in the body of the JSON routes. Raw-body routes (/_files, /_api/fs/archive) take it as a query parameter only.
A scoped call behaves as if issued from inside the session:
- Execs run inside the session’s isolation unit with
cwddefaulting to the session workspace and the session’senvsmerged in. - Filesystem and archive paths resolve inside the workspace; an escape outside it is
403. - Process selectors (tags and pids) see only that session’s processes.
Agent API routes
Session routes
The logs and metrics routes answer CORS, so a browser page holding a token can read them directly.
Process routes
A
selector is a process tag or pid. Processes are detached from the client that started them: dropping the stream never kills the process, and a later connect receives the retained exit code. The keepalive interval of a stream is client-tunable with ?keepalive_s= (default 30).
PTY routes
A terminal-shaped surface over the same process manager, for agents that drive an interactive shell.
Stream a PTY through
GET /_api/process/io?selector= (WebSocket) or GET /_api/process/connect (server-sent events). PTY output is never written to the session log. cpln sandbox session connect is a terminal over this surface.
Filesystem routes
File transfer routes
cpln cp --session moves files and directories through these routes and the archive routes.
Previews and the port proxy
A browser opens either proxy with a one-time code: open the URL with
?preview_code=<code> within 60 seconds of minting it. The daemon sets a cookie (scoped to /_s/<session>/ for a session preview, derived from the token for the port proxy), spends the code, and redirects a GET to the same URL without it. WebSocket upgrades and requests with a body are proxied with the parameter stripped. Codes are spent on first use, so a code read from a URL or an access log opens nothing. An agent calling from code sends the token in the header instead and needs no code.
The daemon’s own ports (49983 and 49984) are never proxyable (403).
Internal routes
/_init bootstraps the daemon’s plaintext token and /_freeze and /_unfreeze are reserved for the platform; they are guarded to loopback and are not part of the client surface.
Agent API run_as
Theuser field on process, PTY, and session create picks the Unix identity a command runs as:
- The default is the session’s default user,
devuser, on the worker’s own root filesystem. - The daemon runs as root in the standard image, so the named user must exist; an unknown user is
400. The child gets that user’s uid, gid, supplementary groups, andHOME,USER, andLOGNAME. - In an image session (a session created with
image), execs run as the image’s root unlessuseris a numeric"uid:gid"such as"1000:1000", because the worker’s user names mean nothing in a foreign root filesystem.
su, setpriv).
Worker environment settings
These environment variables configure the daemon. Set them on the worker’s first container (spec.containers[0].env) when a default does not fit. DEVBOXD_TOKEN and DEVBOXD_MAX_SESSIONS are derived by the platform and cannot be set by you.
Standard agent sandbox image
build.cpln.io/public/agentbox-base:v1 is the image the server injects when an agent sandbox is created without containers (4 CPU and 8 GiB unless sized). It contains:
devboxdas PID 1 on:49983, the only listener.git,curl,python3withpipandvenv,sudo, andrclonefor cloud mounts.runcand gVisor’srunsc, the two nested runtimes sessions can pick.- A non-root
devuserwhose home is the sandbox’s home volume, mounted at/home/devuser.
devboxd on port 49983 can serve as a worker; the standard dev image cannot, because it runs the daemon in a mode that tracks activity only.
Agent API examples
The examples assumeEP is the worker’s endpoint and TOKEN is the sandbox token or the session’s token.
Start a command in a session and stream its output as server-sent events:
cpln workload exec, which does not work on a privileged worker):
Agent API example: an orchestrator
The pattern for a backend that runs many tasks: create sessions with your Control Plane token through the platform API, hand each task its session token, retry on429, and delete when done. In Python with requests:
- The sandbox token stays in this backend; agents only ever see
session["token"]. - Session ids are yours to choose, so use your task id; a duplicate answers
409. - The first call after a quiet period may take a few seconds while the sandbox wakes.
- When one sandbox is not enough, create sessions by identity through
/org/{org}/gvc/<sandbox-gvc>/-sessionsinstead of by name and let the platform spread them over several (the sandbox GVC’s name comes fromGET /org/{org}/gvc/-sandbox); see Scale by identity.