---
title: Ports
description: "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
curl https://api.caged.dev/v1/sandboxes/cage-a1b2c3d4/ports \
  -H "Authorization: Bearer caged_sk_..."
```

**Response** `200 OK`

```json
[
  {
    "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
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
{
  "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.