> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandboxes in the Console

> A tour of the Sandboxes area of the Control Plane Console: the Overview, the create form, the Dev Sandboxes list and Connect panel, Agent Sessions with the New Session form and session view, and the Images page.

The **Sandboxes** area of the [Console](https://console.cpln.io) 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](https://docs.controlplane.com/reference/gvc.md) (`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.

| Card | Shows |
| :- | :- |
| **Dev Sandboxes**, **Agent Sandboxes** | How many are Ready, Starting, Scaled to Zero, Suspended, or Failed; click a count to filter the table below |
| **Sessions** | N live / M active: how many sessions exist, how many are active now, and how many agent sandboxes hold them |
| **Needs Attention** | Failed deployments, sandboxes starting for 15 minutes or more, and sandboxes suspended for 7 days or more |
| **CPU in Use**, **Memory in Use**, **Provisioned Storage** | What your sandboxes consume |

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**.

| State | Meaning |
| :- | :- |
| Ready | Up and answering its readiness probe |
| Starting, Updating | Rolling out |
| Scaled to Zero | Idle; the API reports `suspended` (scaled to zero; the Console shows Scaled to Zero). The next request wakes it |
| Suspended | Stopped on purpose with **Suspend**; nothing wakes it until **Unsuspend** |
| Failed | The deployment failed; open the workload for the reason |

## 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.

| Field | Default | Notes |
| :- | :- | :- |
| Name | | Cannot be changed after creation |
| GVC | The org's sandbox GVC | Read-only: `default` in an org created with the built-in default GVC, `sandboxes` in older orgs, where the form creates it with your first sandbox |
| Type | Dev Sandbox | Or Agent Sandbox |
| Identity | | Optional. An identity of the sandbox GVC; an agent sandbox with one joins that identity's pool |
| Image | Standard | Or one of **Your Sandbox Images**, built on the [Images](#images-page) page |
| IDE | browser | Dev sandboxes only; informational |
| Reserved CPU, Reserved Memory | `1000m`, `2Gi` for a dev sandbox; `4000m`, `8Gi` for an agent sandbox | |
| App Port | `8080` | Dev sandboxes: the port the endpoint root proxies to |
| Extra Ports | | Dev sandboxes: other ports to declare on the container, comma separated |
| Environment Variables | | A value may reference a secret the sandbox's [identity](https://docs.controlplane.com/reference/identity.md) can reveal: `cpln://secret/<name>.<key>` |
| Home Volume: Size (GB) | `20` | Fixed after creation |
| Scale To Zero Delay (seconds) | `300` | Idle seconds before the sandbox scales to zero |

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](https://docs.controlplane.com/guides/sandbox/scaling-workers.md).

See the [sandbox reference](https://docs.controlplane.com/reference/sandbox/general.md) 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](https://docs.controlplane.com/guides/sandbox/dev-sandbox.md#sign-in).

### 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**.

| Column | Meaning |
| :- | :- |
| Session | The session id; opens the session view |
| Status | **Running** (work, an attached client, or recent use), **Idle**, **Paused** (its agent sandbox is scaled to zero; the session resumes on its next use), **Starting**, **Unknown**, or **Ended** with when and why |
| Identity | The identity its agent sandbox runs as |
| Agent Sandbox | The workload holding the session, with its own state: Running, Scaled to zero, Starting, Unknown, or Unreachable |
| Runtime | `runc`, or a **gVisor** tag for `runsc` |
| Image | The session's image, or **worker image** when it runs the sandbox's own filesystem |
| Created | When the session started |

### New Session

| Field | Notes |
| :- | :- |
| Identity | Optional. The session lands on an agent sandbox of that identity with room; one is added when none has |
| Agent sandbox | Optional. Leave it on **Let the platform choose**, or pick one to put the session there regardless of room; each option shows its session count against its limit |
| Id | Optional. Letters, digits, `.`, `_`, `-`, up to 55 characters through the GVC route, since the server appends the agent sandbox's key; generated when empty |
| Runtime | `runc`: near-native speed, same trust domain. `runsc (gVisor)`: a user-space kernel per session, the strongest isolation inside the sandbox |
| Image | Optional OCI image for the session's root filesystem, for example `python:3.12-slim`, or one of the org's agent sandbox images. Empty runs the sandbox's own image. A private image in this org's registry is pulled with a token scoped to it |
| Ports | Comma separated, default `3000`. Each gets a preview URL; any port routes regardless |
| Preview access | **Token** (sandbox or session token, cookie after the first visit) or **Public (anyone with the URL)** |
| Memory limit (MB), CPU limit (millicores) | Optional |
| Log process output | On by default: keep every process's stdout and stderr in the session log; the lifecycle is always logged |

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](https://docs.controlplane.com/reference/sandbox/image.md) 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](https://docs.controlplane.com/guides/sandbox/sandbox-images.md).
