> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox Helper CLI

> Reference for the sandbox command available inside every sandbox — check status, discover ports, and diagnose runtime issues.

## 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

```bash theme={null} theme={null}
sandbox status
```

```text Output theme={null} theme={null}
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

```bash theme={null} theme={null}
sandbox ports
```

```text Output theme={null} theme={null}
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.).

<Tip>
  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.
</Tip>

## sandbox app

```bash theme={null} theme={null}
sandbox app
```

```text Output theme={null} theme={null}
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

```bash theme={null} theme={null}
sandbox doctor
```

```text Output theme={null} theme={null}
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

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>