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

# Work in a dev sandbox

> Sign in to your dev sandbox, open your code, run and preview your app, connect VS Code or Cursor, use the built-in AI coding assistants, and keep your state between sessions.

A dev sandbox is one box for one person: VS Code in the browser, a terminal, SSH for your desktop editor, and your app at a URL. Your home directory lives on a volume that survives restarts. Create one with [Get started with sandboxes](https://docs.controlplane.com/guides/sandbox/getting-started.md); this page is about working in it.

> [!NOTE]
>
> The `cpln sandbox` commands on this page need a current CLI (`cpln sandbox --help` shows what yours supports); they find the org's sandbox GVC themselves, so do not pass `--gvc`.

## Sign in

You sign in with your Control Plane account; there is no password. Anyone with `connect` on the sandbox can open it.

* **From the Console.** Open the sandbox from **Dev Sandboxes** and choose the IDE or the terminal. If the sandbox is scaled to zero, the Console wakes it first.
* **From the CLI.** `cpln sandbox connect my-dev --org my-org` opens the IDE in your browser; `--ide terminal` opens the terminal. Add `--print-url` to get a sign-in link instead, for a browser on another machine. The link opens one browser once and expires in 60 seconds.
* **From the sandbox's own URL.** Opening `/_ide/` without a session shows one button, **Sign in with Control Plane**, which takes you through the Console and back.

A sign-in lasts 8 hours of use, 24 hours at most. Sign out at `/_ide/logout`. If sign-in fails, see [Troubleshooting](#dev-sandbox-troubleshooting).

## Open your code

Your home directory is `/home/devuser`, and `~/workspace` (also reachable as `/workspace`) is where repositories go:

```bash theme={null}
cd ~/workspace
git clone https://github.com/you/your-app.git
```

The image ships `git` and the `gh` CLI. Run `gh auth login` once; the credential is stored in your home and survives restarts. SSH keys under `~/.ssh` persist the same way.

## Run and preview your app

The sandbox's endpoint serves `/` from the app port, `8080` by default (`spec.sandbox.appPort`). Bind your server to `0.0.0.0` so the gateway can reach it:

```bash theme={null}
vite --host 0.0.0.0 --port 8080
next dev -H 0.0.0.0 -p 8080
python manage.py runserver 0.0.0.0:8080
```

Then open the endpoint: `sandbox url 8080` prints it, and the Console's **App** button opens it. Until something listens, the URL shows a waiting page that refreshes every three seconds.

Other ports work too. Anything listening in the box is reachable at `<endpoint>/_port/<n>/` once you are signed in, and `sandbox ports` lists what it found. To serve a different port at `/` without changing the spec:

```bash theme={null}
sandbox set port 3000      # serve port 3000 at the root URL, live
sandbox set port default   # back to the app port
```

An OAuth or IDE callback that cannot carry your sign-in cookie can use `<endpoint>/_callback/<n>/` instead, which needs no sign-in.

## Use a desktop IDE

`cpln sandbox connect` wakes the sandbox if needed, injects your public key, opens a local port-forward to its SSH server, and launches the editor:

```bash theme={null}
cpln sandbox connect my-dev --org my-org --ide vscode
cpln sandbox connect my-dev --org my-org --ide cursor
cpln sandbox connect my-dev --org my-org --ide ssh            # tunnel only
cpln sandbox connect my-dev --org my-org --ide ssh --local-port 2222
```

The SSH mode prints a host alias, `cpln-dev-my-dev.<gvc>.<org>` (`<gvc>` is the org's sandbox GVC), for `ssh cpln-dev-my-dev.<gvc>.<org>` or as a Remote-SSH host. VS Code and Cursor reconnect with:

```bash theme={null}
code --remote ssh-remote+cpln-dev-my-dev.<gvc>.<org> /workspace
cursor --classic --remote ssh-remote+cpln-dev-my-dev.<gvc>.<org> /workspace
```

Keep the command running; Ctrl+C closes the tunnel.

> [!NOTE]
>
> VS Code and Cursor install their server into the sandbox on first connect. The sandbox keeps those trees on fast local disk and links them from your home, so the first connect is quick. They are caches and are re-downloaded after a restart.

## Use the AI coding assistants

The standard image ships Claude Code and Codex, so an agent can work on your code inside the sandbox instead of on your laptop:

```bash theme={null}
cd ~/workspace/your-app
claude        # Claude Code
codex         # Codex CLI
```

Each needs its provider key. Export it in the terminal for the session, add it to `~/.bashrc` to keep it (your home persists), or inject it as an environment variable on the sandbox whose value references a [secret](https://docs.controlplane.com/reference/secret.md) the sandbox's [identity](https://docs.controlplane.com/reference/identity.md) can reveal, `cpln://secret/<name>.<key>`, so the key never sits in a file.

The image pins its tool versions. Set `SANDBOX_REFRESH_TOOLS=true` as an environment variable on the sandbox to install the latest Claude Code and Codex at boot; they land in `~/.npm-global`, take precedence, and persist.

Inside the sandbox, `cpln` is signed in as the sandbox's own identity (`CPLN_TOKEN`). Interactive shells move that token to `CPLN_WORKLOAD_TOKEN`, so `cpln login` signs in as you when you need your own permissions.

## Keep things between sessions

Everything under `/home/devuser` is on the home volume (20 GB by default; pick a size at creation, it is fixed afterwards):

* Your repositories in `~/workspace`.
* Git and `gh` credentials, SSH keys, shell config, IDE settings and extensions.
* Packages you install: `~/.npm-global` and `~/.local` are on `PATH`, and `pip` installs as the user by default, so `npm install -g` and `pip install` survive restarts.
* Ports you chose with `sandbox set port`.

Anything outside your home (`apt install`, files in `/opt`) is image content and resets when the container restarts. To bake tools into the image, build a [sandbox image](https://docs.controlplane.com/guides/sandbox/sandbox-images.md) and create the sandbox with `cpln sandbox create <ref> --image //sandboximage/<name>`, which resolves a ready dev sandbox image to its built reference. That form is refused for `--type worker`, for an agent-type image, for an unbuilt or failed build (`cpln sandboximage buildlog <name> -f` shows why), and for a GVC-scoped link.

## When you step away

After 5 minutes (`scaleToZeroDelay`, 30 to 3600 seconds) with no request on the endpoint and nothing working inside, the sandbox suspends in place. A build, a test run, a dev server, or an agent you left running counts as work and keeps it up; an open but idle editor does not. Opening the sandbox, connecting, or hitting its URL wakes it. Files persist; running processes and tmux sessions do not.

To stop it on purpose, `cpln sandbox stop my-dev --org my-org` (or **Suspend** on its row in the Console). Nothing wakes a suspended sandbox until `cpln sandbox start my-dev --org my-org` (**Unsuspend** in the Console).

## Dev sandbox troubleshooting

> [accordion] The root URL shows 'Waiting for app'
>
> No process listens on the app port. Start your app bound to `0.0.0.0:<APP_PORT>`, switch the primary port with `sandbox set port <n>`, or open a detected port from `sandbox ports`.

> [accordion] The Console or CLI says the sandbox did not issue a sign-in link
>
> Sign-in runs a command inside the sandbox as you, and that is refused when your account lacks `connect` on this workload. Ask an org admin for a [policy](https://docs.controlplane.com/reference/policy.md) that grants `connect` on the sandbox, then sign in again.

> [accordion] 'This sign-in link was already used or has expired.'
>
> A sign-in link opens one browser once and lives 60 seconds. Open the sandbox again from the Console, or run `cpln sandbox connect` again.

> [accordion] 'This sandbox runs an image from before browser sign-in by one-time link.'
>
> The sandbox was built before the current sign-in flow. Rebuild its [sandbox image](https://docs.controlplane.com/guides/sandbox/sandbox-images.md) on the current base and redeploy.

> [accordion] The sign-in page cannot be reached or hangs
>
> The box may be scaled to zero and waking. The Console and the CLI wait for it; a direct visit to `/_ide/` wakes it too, so refresh after a few seconds.

> [accordion] /\_ide/ answers 'IDE unavailable' (503)
>
> The gateway is up but code-server is still starting or failed. Wait a moment; `sandbox status` shows the IDE and terminal states.

> [accordion] A port is detected but /\_port/\<n>/ returns 502
>
> The service binds to a specific interface. Bind it to `0.0.0.0` or `127.0.0.1`.

> [accordion] The sandbox never scales to zero
>
> Something inside is working: a dev server, a file watcher, or an agent left running counts as activity. Stop it, or raise `scaleToZeroDelay` if the churn is expected.

> [accordion] A process keeps running after you close the tab
>
> Each surface attaches to its own tmux session: `vscode` for the IDE terminal, `term` for the browser terminal, `ssh` for SSH. Closing the tab detaches; the process keeps running and counts as activity. `tmux ls` lists the sessions; `tmux kill-session -t <name>` ends one.

## How it works

> [accordion] Ports and gateway routes
>
> One gateway on port 8888 is the workload endpoint. It signs you in and proxies to everything else.
>
> | Path | Backend | Sign-in | Purpose |
> | :- | :- | :- | :- |
> | `/` | app port (`8080`) | No | Your app, or a waiting page |
> | `/_ide/` | code-server on 8443 | Yes | Browser IDE |
> | `/_term/` | ttyd on 7681 | Yes | Browser terminal |
> | `/_port/<n>/` | local port `n` | Yes | Any other port, including WebSocket upgrades |
> | `/_callback/<n>/` | local port `n` | No | IDE and OAuth callbacks; refuses the reserved ports |
> | `/_ide/login`, `/_ide/logout` | gateway | | Sign-in page and sign-out |
> | `/_status`, `/_ports` | gateway | No | JSON runtime status and detected ports |
> | `/_livez`, `/healthz` | gateway | No | Liveness (loading it wakes the box) and readiness |
>
> SSH is on port 22, reached only through the tunnel `cpln sandbox connect` opens. Ports 22, 7681, 8443, 8888, 49983, and 49984 are reserved and cannot be the app port.

> [accordion] How sign-in works
>
> Access is a Control Plane permission, and no Control Plane credential ever reaches the box. The Console or the CLI runs a small command inside the sandbox through exec, which the platform allows only for callers with `connect` on the workload. That command mints a one-time code; your browser presents it to the gateway's own sign-in page, which keeps an opaque session cookie of its own. A code is spent on first use and lives 60 seconds.
>
> | Sign-in page message | Cause |
> | :- | :- |
> | `This sign-in link was already used or has expired. Sign in again.` | Spent or older than 60 seconds |
> | `Sign in from this sandbox's own page.` | The code was posted from another site |

> [accordion] The sandbox helper command
>
> Every dev sandbox ships a `sandbox` command (alias `devbox`) that needs no credentials:
>
> | Command | What it does |
> | :- | :- |
> | `sandbox status` | Runtime service status (gateway, IDE, terminal, app) and memory usage |
> | `sandbox ports` | Detected local ports with their external paths |
> | `sandbox url <port>` | Print the external URL for a port (`sandbox open <port>` does the same) |
> | `sandbox app` | The primary app port and common run hints |
> | `sandbox set port <n>` | Serve port `n` at the root URL, live |
> | `sandbox set port default` | Revert the root URL to the sandbox default |
> | `sandbox doctor` | Check installed runtimes and sandbox basics |
>
> `sandbox set port` writes `/home/devuser/.devbox-app-port`, so a chosen port survives restarts.

> [accordion] What is in the standard image
>
> What the image contains is listed in [What the sandbox layer adds](https://docs.controlplane.com/reference/sandbox/image.md#what-the-sandbox-layer-adds).
>
> tmux is configured to stay out of the way: no status bar, no prefix. code-server offers a terminal profile named **persistent** that attaches to a tmux session called `vscode`. To use tmux key bindings, add a prefix:
>
> ```bash theme={null}
> echo "set -g prefix C-a" >> ~/.tmux.conf
> tmux source-file ~/.tmux.conf
> ```
