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

# Getting Started with Sandbox

> Create a cloud development environment with a browser IDE, terminal, and persistent storage in under five minutes.

## Prerequisites

| Requirement                | Purpose                                                          |
| :------------------------- | :--------------------------------------------------------------- |
| A Control Plane org        | With at least one GVC                                            |
| Access to the CPLN Console | The Sandbox Manager runs as an embedded app in `console.cpln.io` |
| `cpln` CLI (optional)      | Required for `cpln sandbox connect` (desktop IDE and SSH access) |

<Note>
  VS Code Desktop and JetBrains Gateway are optional. The browser IDE (code-server) and terminal (ttyd) require zero local installs.
</Note>

## Open the Sandbox Manager

The Sandbox Manager is embedded in the CPLN Console. Navigate to the **Sandbox** section for your org.

## Create a Toolbox Image (Optional)

Several sandbox templates are available to begin working immediately. These images include core runtimes and libraries for common development workflows. To customize a template or build from scratch:

<Steps>
  <Step title="Navigate to Images">
    Click **Images** in the sidebar.
  </Step>

  <Step title="Start a new build">
    Click **New Image**.
  </Step>

  <Step title="Choose a build mode">
    * **From Template** — select runtimes, packages, and tools interactively
    * **BYOI** — provide an existing OCI image reference
  </Step>

  <Step title="Build">
    Click **Build** and wait for the build to complete.
  </Step>
</Steps>

See [Building Toolbox Images](/guides/sandbox/toolbox-images) for details.

## Create a Sandbox

<Steps>
  <Step title="Navigate to Instances">
    Click **Instances** in the sidebar, then click **New Instance**.
  </Step>

  <Step title="Configure the sandbox">
    * **Name** (optional) — unique environment name
    * **Image** — select a sandbox image
    * **Size** (Medium pre-selected) — CPU/memory profile
    * **App Port** — port your app will listen on (default: 8080)
    * **Identity** and **Secrets** — optional access to private infrastructure
  </Step>

  <Step title="Create">
    Click **Create**. The sandbox provisions a persistent volume and workload, then becomes ready in \~60–90 seconds.
  </Step>
</Steps>

<Tip>
  Create a single-location [GVC](/reference/gvc) for your sandboxes. This reduces costs and provides the optimal developer experience.
</Tip>

## Connect Your IDE

Once the instance shows **Ready**, use the connect panel or the CLI.

### From the Web UI

The connect panel shows direct links and the IDE password:

| Feature                   | Access                                           |
| :------------------------ | :----------------------------------------------- |
| Browser IDE (code-server) | `https://<endpoint>/_ide/` (password-protected)  |
| Browser terminal (ttyd)   | `https://<endpoint>/_term/` (password-protected) |
| Public app URL            | `https://<endpoint>/` (shareable)                |

### From the CLI

The `cpln sandbox connect` command sets up SSH tunnels for desktop IDE access. It automatically finds your sandbox by searching your accessible orgs and GVCs:

```bash theme={null} theme={null}
# Open in VS Code (default)
cpln sandbox connect <my-sandbox>

# Open in Cursor
cpln sandbox connect <my-sandbox> --ide cursor

# Direct SSH session
cpln sandbox connect <my-sandbox> --ide ssh

# Open browser IDE
cpln sandbox connect <my-sandbox> --ide browser
```

Specify org and GVC explicitly for faster lookup:

```bash theme={null} theme={null}
cpln sandbox connect <my-sandbox> --org acme --gvc dev
```

## Start Coding

Clone your repo and install dependencies from the IDE terminal. For private repos, authenticate git inside the environment:

```bash theme={null} theme={null}
gh auth login          # GitHub
glab auth login        # GitLab (if installed)
```

Credentials stored under `/root` survive suspend/resume because `/root` is backed by a persistent [volumeset](/reference/volumeset). They are removed when the environment is deleted.

## Suspend and Resume

Suspend to save costs when you're done for the day. Your full state is preserved.

| Action      | Effect                                             | Cost              |
| :---------- | :------------------------------------------------- | :---------------- |
| **Suspend** | Workload scaled to zero, volumeset retained        | Storage only      |
| **Resume**  | Workload scales back up, mounts existing volumeset | Compute + storage |
| **Delete**  | Workload and volumeset removed                     | None              |

Use the **Suspend** and **Resume** buttons in the Instances list or connect panel.

<Warning>
  Deleting an environment removes the workload and volumeset permanently, including cloned repos, credentials, IDE settings, and uncommitted changes. Use suspend to preserve state.
</Warning>