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 withconnect 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-orgopens the IDE in your browser;--ide terminalopens the terminal. Add--print-urlto 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.
/_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:
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:
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:
<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:
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:
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:~/.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
ghcredentials, SSH keys, shell config, IDE settings and extensions. - Packages you install:
~/.npm-globaland~/.localare onPATH, andpipinstalls as the user by default, sonpm install -gandpip installsurvive restarts. - Ports you chose with
sandbox set port.
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
The root URL shows 'Waiting for app'
The root URL shows 'Waiting for app'
0.0.0.0:<APP_PORT>, switch the primary port with sandbox set port <n>, or open a detected port from sandbox ports.The Console or CLI says the sandbox did not issue a sign-in link
The Console or CLI says the sandbox did not issue a sign-in link
connect on this workload. Ask an org admin for a policy that grants connect on the sandbox, then sign in again.'This sign-in link was already used or has expired.'
'This sign-in link was already used or has expired.'
cpln sandbox connect again.'This sandbox runs an image from before browser sign-in by one-time link.'
'This sandbox runs an image from before browser sign-in by one-time link.'
The sign-in page cannot be reached or hangs
The sign-in page cannot be reached or hangs
/_ide/ wakes it too, so refresh after a few seconds.A port is detected but /_port/<n>/ returns 502
A port is detected but /_port/<n>/ returns 502
0.0.0.0 or 127.0.0.1.The sandbox never scales to zero
The sandbox never scales to zero
scaleToZeroDelay if the churn is expected.A process keeps running after you close the tab
A process keeps running after you close the tab
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
Ports and gateway routes
Ports and gateway routes
cpln sandbox connect opens. Ports 22, 7681, 8443, 8888, 49983, and 49984 are reserved and cannot be the app port.How sign-in works
How sign-in works
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.The sandbox helper command
The sandbox helper command
sandbox command (alias devbox) that needs no credentials:sandbox set port writes /home/devuser/.devbox-app-port, so a chosen port survives restarts.What is in the standard image
What is in the standard image
vscode. To use tmux key bindings, add a prefix: