Choose a sandbox type
Prerequisites
- An org. Every sandbox lives in the org’s sandbox GVC, tagged
cpln/sandboxGvc:defaultin orgs created with the built-in default GVC, otherwisesandboxes, created with your first sandbox;GET /org/{org}/gvc/-sandboxnames it. Creating that GVC needscreateon GVCs, only when the org has no sandbox GVC yet. connecton the sandbox to sign in to a dev sandbox or create sessions on an agent sandbox;viewto see it.- The
cplnCLI if you want to work from your terminal. Thecpln sandboxcommands find the org’s sandbox GVC themselves; do not pass--gvc. They need a current CLI; runcpln sandbox --helpto see what yours supports.
Dev sandbox in five minutes
1
Create it
- Console UI
- CLI
Open Sandboxes in the Console, start a new sandbox, give it a name, keep Dev Sandbox, and create. The GVC field is fixed to the org’s sandbox GVC; every other field has a default.
2
Open the IDE
In the Console, open the sandbox from Dev Sandboxes and choose the IDE. From your terminal:Either way you are signed in as yourself. There is no password.
3
Get your code in and run it
In the IDE’s terminal:Bind the server to
0.0.0.0 on port 8080, the sandbox’s app port. ~/workspace is on the home volume, so the clone survives restarts.4
Open your app
The sandbox’s endpoint serves your app at
/. Print it from inside the box with sandbox url 8080, or use the App button in the Console. Until something listens on the port, the URL shows a waiting page.Agent sandbox in five minutes
1
Create it
type: worker in the spec; the Console form does the same with Type: Agent Sandbox. The server sizes it at 4 CPU and 8 GiB and generates its token.2
Open a session
A session is where one task runs: its own workspace, its own container, its own token.
3
Run something and get the result back
cpln cp my-agent:out.json ./out.json --session task-1 --org my-org.4
End the session
When you walk away
- It suspends itself. After 5 minutes with no requests and nothing running inside (a build or an agent you left going keeps it up), the sandbox suspends in place. Opening it again wakes it in seconds. Files stay; running processes do not. Set
scaleToZeroDelay(30 to 3600 seconds) to change the wait. - Suspend it on purpose.
cpln sandbox stop my-dev --org my-orgstops it untilcpln sandbox start my-dev --org my-org. Nothing wakes it in between. The Console offers the same on the sandbox’s row as Suspend and Unsuspend. - Delete it.
cpln sandbox delete my-dev --org my-orgremoves the sandbox and its home volume.
Next steps
Work in a dev sandbox
Sign in, run your app, use desktop IDEs and AI assistants, keep your state.
Run agents in an agent sandbox
Give agents tasks in sessions, from the CLI or your own code.
Scale agent sandboxes by identity
Let the server add and remove agent sandboxes as sessions come and go.
Sandbox reference
Every field of spec.sandbox and what the server fills in.