Sandbox Helper CLI - Control Plane

Overview

Every sandbox includes a sandbox command for inspecting runtime state, discovering ports, and diagnosing issues. No credentials required.

Commands

Command	Description
`sandbox status`	Show runtime service status and resource usage
`sandbox ports`	Show detected local ports and external URLs
`sandbox url <port>`	Print the external URL for a specific port
`sandbox app`	Show primary app port and common run hints
`sandbox doctor`	Check installed runtimes and sandbox basics

sandbox status

sandbox status

Output

Sandbox: ready - Sandbox ready
Primary app port: 8080
Root URL: https://dev-alice-x7k2m.cpln.app/

gateway:8888: ready - Gateway listening
codeServer:8443: ready - code-server listening
terminal:7681: ready - Terminal listening
app:8080: waiting - No app listening on APP_PORT

memory: 412MiB / 16GiB, peak 1.2GiB

The app service shows waiting until you start a process on APP_PORT. This is normal.

sandbox ports

sandbox ports

Output

Sandbox ports

8080  Primary app  root   https://dev-alice-x7k2m.cpln.app/
3000  Next.js      prefix https://dev-alice-x7k2m.cpln.app/_port/3000/
5173  Vite         prefix https://dev-alice-x7k2m.cpln.app/_port/5173/

Tip: bind dev servers to 0.0.0.0 so the gateway can reach them.

A background scanner detects non-reserved TCP listeners every 10 seconds. Ports are auto-labeled based on process name and common conventions (Vite, Next.js, Django, Flask, Rails, etc.).

Secondary ports use prefix routing (/_port/3000/). Most dev servers work without changes. Bind to 0.0.0.0 to ensure the gateway can reach them.

sandbox app

sandbox app

Output

Primary app port: 8080
Root URL: https://dev-alice-x7k2m.cpln.app/

Common run examples:
  vite --host 0.0.0.0 --port 8080
  next dev -H 0.0.0.0 -p 8080
  python manage.py runserver 0.0.0.0:8080
  rails server -b 0.0.0.0 -p 8080

sandbox doctor

sandbox doctor

Output

Sandbox doctor

Runtime checks
  git          git version 2.43.0
  node         v20.18.0
  npm          10.8.2
  python       Python 3.12.7
  go           go version go1.23.0 linux/amd64
  code-server  4.96.4
  gh           gh version 2.63.0

Sandbox
  status       ready
  app port     8080
  app url      https://dev-alice-x7k2m.cpln.app/
  workspace    /root/workspace

Only installed tools are shown. Missing tools are silently omitted.

Troubleshooting

sandbox: command not found

The helper is installed during image build. Rebuild the toolbox image to get the latest version. As a workaround, check status files directly: cat /tmp/devbox-status.json | jq .status.

sandbox ports shows no ports

The port scanner runs every 10 seconds. Wait a few seconds after starting a service, then retry. Verify your service is listening: ss -tlnp | grep LISTEN.

Port shows but URL returns 502

Verify the service binds to 0.0.0.0 or 127.0.0.1, not a specific interface. Check sandbox status for service states.

Terminal & tmux Multi-Repo Workspaces

⌘I

​Overview

​Commands

​sandbox status

​sandbox ports

​sandbox app

​sandbox doctor

​Troubleshooting

Overview

Commands

sandbox status

sandbox ports

sandbox app

sandbox doctor

Troubleshooting