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

# Ports

> List detected ports and manage preview URLs.

# Ports

Caged automatically scans for listening TCP ports inside a sandbox and exposes them as public preview URLs.

## List Ports

Returns all currently detected listening ports for a sandbox.

```bash theme={null}
curl https://api.caged.dev/v1/sandboxes/cage-a1b2c3d4/ports \
  -H "Authorization: Bearer caged_sk_..."
```

**Response** `200 OK`

```json theme={null}
[
  {
    "port": 3000,
    "protocol": "http",
    "preview_url": "https://cage-a1b2c3d4-3000.preview.caged.dev",
    "protected": false,
    "detected_at": "2026-06-08T10:02:00Z"
  },
  {
    "port": 5432,
    "protocol": "tcp",
    "preview_url": null,
    "protected": false,
    "detected_at": "2026-06-08T10:02:00Z"
  }
]
```

## Port Fields

| Field         | Type    | Description                            |
| ------------- | ------- | -------------------------------------- |
| `port`        | integer | Port number                            |
| `protocol`    | string  | `http` or `tcp`                        |
| `preview_url` | string  | Public URL (HTTP ports only)           |
| `protected`   | boolean | Whether password protection is enabled |
| `detected_at` | string  | When the port was first detected       |

## Password-Protect a Port

Add password protection to a preview URL.

<ParamField body="password" type="string" required>
  Password required to access the preview URL.
</ParamField>

```bash theme={null}
curl -X POST https://api.caged.dev/v1/sandboxes/cage-a1b2c3d4/ports/3000/protect \
  -H "Authorization: Bearer caged_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"password": "mypreview123"}'
```

**Response** `200 OK`

```json theme={null}
{
  "port": 3000,
  "protected": true,
  "preview_url": "https://cage-a1b2c3d4-3000.preview.caged.dev"
}
```

## How Port Detection Works

1. Caged scans `/proc/net/tcp` inside the sandbox every 2 seconds
2. New listening ports are registered in the port registry
3. HTTP ports (80, 3000, 4200, 5173, 8000, 8080, etc.) get public preview URLs
4. Non-HTTP ports (databases, etc.) are listed but not publicly exposed
5. Ports are removed when they stop listening

## Rate Limits

Preview URLs are rate-limited to **100 requests per minute** per port.