Skip to main content
An agent sandbox (a sandbox of type 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 the X-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.
The sandbox token is a bearer credential for the whole worker. Hand agents a session token where you can, and keep the sandbox token in the orchestrator that creates sessions.

Session scoping of Agent API routes

Every process, PTY, filesystem, and archive route accepts an optional session=<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 cwd defaulting to the session workspace and the session’s envs merged 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.
A call without a session runs at the worker level, outside any session, with the sandbox token only.

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).
DEVBOXD_PORT_PROXY_PUBLIC=true on the worker container opens /_port/<n>/ without a token, for public preview URLs. Every port bound to localhost on the worker (dev servers, debuggers, anything on 127.0.0.1) then becomes reachable by anyone holding the endpoint URL. Set it only when that is the intent; per-session previews with preview: public are the narrower choice.

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

The user 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, and HOME, USER, and LOGNAME.
  • In an image session (a session created with image), execs run as the image’s root unless user is a numeric "uid:gid" such as "1000:1000", because the worker’s user names mean nothing in a foreign root filesystem.
Session containers carry the Docker default capability set minus host-facing ones, so root inside a session can switch identity (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:
  • devboxd as PID 1 on :49983, the only listener.
  • git, curl, python3 with pip and venv, sudo, and rclone for cloud mounts.
  • runc and gVisor’s runsc, the two nested runtimes sessions can pick.
  • A non-root devuser whose home is the sandbox’s home volume, mounted at /home/devuser.
Any image that runs 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 assume EP 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:
Upload a file into the session workspace, then read it back:
List the processes of a session and stop one by tag:
Fetch a preview of a dev server the session runs on port 3000, from code:
Open the same preview in a browser with a one-time code:
Run a command at the worker level, outside any session, with the sandbox token (this is the replacement for 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 on 429, and delete when done. In Python with requests:
Notes for a real one:
  • 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>/-sessions instead of by name and let the platform spread them over several (the sandbox GVC’s name comes from GET /org/{org}/gvc/-sandbox); see Scale by identity.