Skip to main content
A sandbox gives you a persistent cloud environment in one call. A dev sandbox is a browser IDE and terminal for a person; an agent sandbox is a box where AI agents run code in isolated sessions. Your files live on a home volume that survives restarts, and the sandbox suspends itself when nobody is using it. This page creates one of each, gets you inside, and explains what happens when you walk away. For the model behind it see the sandbox concept; for every field see the sandbox reference.

Choose a sandbox type

Prerequisites

  • An org. Every sandbox lives in the org’s sandbox GVC, tagged cpln/sandboxGvc: default in orgs created with the built-in default GVC, otherwise sandboxes, created with your first sandbox; GET /org/{org}/gvc/-sandbox names it. Creating that GVC needs create on GVCs, only when the org has no sandbox GVC yet.
  • connect on the sandbox to sign in to a dev sandbox or create sessions on an agent sandbox; view to see it.
  • The cpln CLI if you want to work from your terminal. The cpln sandbox commands find the org’s sandbox GVC themselves; do not pass --gvc. They need a current CLI; run cpln sandbox --help to see what yours supports.

Dev sandbox in five minutes

1

Create it

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.
The sandbox shows Ready within a minute or two.
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.
Everything else about a dev sandbox, from desktop IDEs to the AI coding assistants it ships with, is in Work in a dev sandbox.

Agent sandbox in five minutes

1

Create it

An agent sandbox is 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

The command’s output streams to your terminal and its exit code becomes the CLI’s. Files the task writes come back the same way: cpln cp my-agent:out.json ./out.json --session task-1 --org my-org.
4

End the session

The session’s log stays readable afterwards. The sandbox keeps running for the next task and suspends itself when idle.
Doing the same from your own code, with per-task images, previews, logs, and an orchestrator pattern, is in Run agents in an agent sandbox.

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-org stops it until cpln 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-org removes the sandbox and its home volume.
Deleting a sandbox deletes its home volume: cloned repos, credentials, IDE settings, installed packages, and session logs. Suspend it instead when you want to keep the state.

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.