Skip to main content
The Sandboxes area of the Console is where you create sandboxes, open them, and watch the sessions of your agent sandboxes. It is an org-level area with four tabs: Overview, Dev Sandboxes, Agent Sessions, and Images. Everything in it lives in the org’s sandbox GVC (default in an org created with the built-in default GVC, sandboxes in older orgs), which the Console switches your context to once a sandbox exists. An agent sandbox is type: worker; the reference says worker when it means the workload.

Overview

The Overview is the place to see what is running and what needs attention. Below the cards, one table lists every sandbox with its Type, State, Size, Sessions (agent sandboxes), and Modified date. The row actions open a dev sandbox’s IDE (VS Code) or terminal, the Connect panel (labelled API on an agent sandbox), and Suspend, Unsuspend, and Delete.

Create form

The create form opens from the Sandboxes area. The type picker swaps the standard image and size. When the org lacks the sandbox location, a location missing page replaces the form. Agent sandbox scaling (maxSessions and the pool fields) is not on the form; set it through the CLI or API as described in Scale agent sandboxes by identity. See the sandbox reference for what the server adds to the workload.

Dev Sandboxes

The Dev Sandboxes tab lists your dev sandboxes with the columns Endpoint, Readiness, Size, Suspended, Last Modified, and Actions. From a row you can open the IDE (VS Code) or the Terminal in a new tab, or open the Connect panel. Opening the IDE or terminal signs you in: the Console wakes the sandbox if it is scaled to zero, runs the sign-in command inside it as you (which needs connect on the workload), and sends your browser to the sandbox with a one-time code. No password and no Control Plane token reach the box. See Sign in to the IDE and terminal.

Connect Panel

Connect opens a panel whose cards depend on the type.
  • Dev Sandbox: Open in Browser (IDE, Terminal, App) and Connect From Your Terminal, where you pick VS Code, Cursor, or SSH and copy the matching cpln sandbox connect command.
  • Agent Sandbox: Endpoint and Token, with the endpoint and the sandbox token (shown only to users with connect on the workload), and Connect From Your Terminal, with the commands that create a session and run a command in it.

Agent Sessions

The Agent Sessions tab is one table of every session in the sandbox GVC. Filter it by Active, Ended, or All, and by identity. Active reads the platform’s records and wakes no sandbox; Ended and All probe every agent sandbox and wake the scaled-to-zero ones. Create Agent Sandbox sits beside New Session.

New Session

The result shows the Session token once. Copy it if your agent will authenticate with the session token rather than the sandbox token.

Session View

Opening a session shows its tabs:
  • Preview: opens a declared port, or any port you type, in an embedded frame or a new tab. The Console mints a one-time code for it, so no token appears in the URL.
  • Processes: PID, tag, command, and working directory of each process, with Terminate (SIGTERM) and Kill (SIGKILL).
  • Connect: the curl calls that run a command in this session and open its preview, with the sandbox token filled in.
  • Logs: the session log with a search box and a level filter (all levels, warn and up, errors).
  • Metrics: charts for CPU as a percentage of allotted cores, memory (used, cache, limit), and disk (session scratch and workspace).
While the agent sandbox is awake, logs and processes are read from it live. While it is scaled to zero, logs and metrics come from the platform’s stores, so looking at a session never wakes its sandbox.

Ended Sessions

Ended sessions stay in the table under Ended with when and why they ended. A session whose agent sandbox was deleted or replaced is listed as archived, with its logs and metrics still readable from the platform’s stores.

Images page

The Images page lists the org’s sandbox images with the columns Type (Dev Image or Agent Image), Build (the build phase), Image (the built reference), and Base (the base image it builds on). Create a dev image to add the sandbox layer on top of your own base image and select it in the create form, or an agent image to copy your base alone into the org registry and select it in the New Session form. See Build a sandbox image.