Getting Started with Sandbox

Create a cloud development environment with a browser IDE, terminal, and persistent storage in under five minutes.

Prerequisites

Requirement	Purpose
A Control Plane org	With at least one GVC
Access to the CPLN Console	The Sandbox Manager runs as an embedded app in console.cpln.io
cpln CLI (optional)	Required for cpln sandbox connect (desktop IDE and SSH access)

VS Code Desktop and JetBrains Gateway are optional. The browser IDE (code-server) and terminal (ttyd) require zero local installs.

Open the Sandbox Manager

The Sandbox Manager is embedded in the CPLN Console. Navigate to the Sandbox section for your org.

Create a Toolbox Image (Optional)

Several sandbox templates are available to begin working immediately. These images include core runtimes and libraries for common development workflows. To customize a template or build from scratch:

1. Navigate to Images

   Click Images in the sidebar.

2. Start a new build

   Click New Image.

3. Choose a build mode

   • From Template — select runtimes, packages, and tools interactively
   • BYOI — provide an existing OCI image reference
4. Build

   Click Build and wait for the build to complete.

See Building Toolbox Images for details.

Create a Sandbox

1. Navigate to Instances

   Click Instances in the sidebar, then click New Instance.

2. Configure the sandbox

   • Name (optional) — unique environment name
   • Image — select a sandbox image
   • Size (Medium pre-selected) — CPU/memory profile
   • App Port — port your app will listen on (default: 8080)
   • Identity and Secrets — optional access to private infrastructure
3. Create

   Click Create. The sandbox provisions a persistent volume and workload, then becomes ready in ~60–90 seconds.

Create a single-location GVC for your sandboxes. This reduces costs and provides the optimal developer experience.

Connect Your IDE

Once the instance shows Ready, use the connect panel or the CLI.

From the Web UI

The connect panel shows direct links and the IDE password:

Feature	Access
Browser IDE (code-server)	https://<endpoint>/_ide/ (password-protected)
Browser terminal (ttyd)	https://<endpoint>/_term/ (password-protected)
Public app URL	https://<endpoint>/ (shareable)

From the CLI

The cpln sandbox connect command sets up SSH tunnels for desktop IDE access. It automatically finds your sandbox by searching your accessible orgs and GVCs:

# Open in VS Code (default)
cpln sandbox connect <my-sandbox>

# Open in Cursor
cpln sandbox connect <my-sandbox> --ide cursor

# Direct SSH session
cpln sandbox connect <my-sandbox> --ide ssh

# Open browser IDE
cpln sandbox connect <my-sandbox> --ide browser

Specify org and GVC explicitly for faster lookup:

cpln sandbox connect <my-sandbox> --org acme --gvc dev

Start Coding

Clone your repo and install dependencies from the IDE terminal. For private repos, authenticate git inside the environment:

gh auth login          # GitHub
glab auth login        # GitLab (if installed)

Credentials stored under /root survive suspend/resume because /root is backed by a persistent volumeset. They are removed when the environment is deleted.

Suspend and Resume

Suspend to save costs when you’re done for the day. Your full state is preserved.

Action	Effect	Cost
Suspend	Workload scaled to zero, volumeset retained	Storage only
Resume	Workload scales back up, mounts existing volumeset	Compute + storage
Delete	Workload and volumeset removed	None

Use the Suspend and Resume buttons in the Instances list or connect panel.

Deleting an environment removes the workload and volumeset permanently, including cloned repos, credentials, IDE settings, and uncommitted changes. Use suspend to preserve state.