Skip to main content

​
Prerequisites

RequirementPurpose
A Control Plane orgWith at least one GVC
Access to the CPLN ConsoleThe 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:
FeatureAccess
Browser IDE (code-server)https://<endpoint>/_ide/ (password-protected)
Browser terminal (ttyd)https://<endpoint>/_term/ (password-protected)
Public app URLhttps://<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.
ActionEffectCost
SuspendWorkload scaled to zero, volumeset retainedStorage only
ResumeWorkload scales back up, mounts existing volumesetCompute + storage
DeleteWorkload and volumeset removedNone
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.