Skip to main content

​
Overview

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

​
Commands

CommandDescription
sandbox statusShow runtime service status and resource usage
sandbox portsShow detected local ports and external URLs
sandbox url <port>Print the external URL for a specific port
sandbox appShow primary app port and common run hints
sandbox doctorCheck 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

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.
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.
Verify the service binds to 0.0.0.0 or 127.0.0.1, not a specific interface. Check sandbox status for service states.