Skip to main content
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; this page is about working in it.
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.

Open your code

Your home directory is /home/devuser, and ~/workspace (also reachable as /workspace) is where repositories go:
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:
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:
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:
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:
Keep the command running; Ctrl+C closes the tunnel.
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:
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 the sandbox’s identity 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 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

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.
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.
The gateway is up but code-server is still starting or failed. Wait a moment; sandbox status shows the IDE and terminal states.
The service binds to a specific interface. Bind it to 0.0.0.0 or 127.0.0.1.
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.
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

One gateway on port 8888 is the workload endpoint. It signs you in and proxies to everything else.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.
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.
Every dev sandbox ships a sandbox command (alias devbox) that needs no credentials:sandbox set port writes /home/devuser/.devbox-app-port, so a chosen port survives restarts.
What the image contains is listed in 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: