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

# Port Forwarding

> Access web servers and services running inside sandboxes.

# Port Forwarding

When an agent starts a web server, database, or any TCP service inside a sandbox, Caged automatically detects it and generates a public preview URL.

## How It Works

1. Caged scans `/proc/net/tcp` inside the sandbox every 2 seconds
2. New listening ports are detected and registered
3. HTTP ports get public preview URLs with HTTPS
4. The proxy routes requests from the preview URL to the sandbox

```
Browser → https://cage-a1b2c3d4-3000.preview.caged.dev
                     ↓
              Caged Reverse Proxy
                     ↓
              Sandbox VM :3000
```

## Viewing Ports

### CLI

```bash theme={null}
caged ports cage-a1b2c3d4
```

```
PORT   PROTOCOL   PREVIEW URL                                        PROTECTED
3000   http       https://cage-a1b2c3d4-3000.preview.caged.dev      no
8080   http       https://cage-a1b2c3d4-8080.preview.caged.dev      no
5432   tcp        —                                                   no
```

### API

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

### Dashboard

The sandbox detail page shows all detected ports with clickable preview links.

## Password Protection

Add a password to restrict access to a preview URL:

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

Visitors will be prompted for the password before accessing the preview.

## Recognized HTTP Ports

These ports automatically get preview URLs:

| Port | Common Use              |
| ---- | ----------------------- |
| 80   | HTTP                    |
| 3000 | React, Next.js, Express |
| 4200 | Angular                 |
| 5173 | Vite                    |
| 5000 | Flask                   |
| 8000 | Django, FastAPI         |
| 8080 | General HTTP            |
| 8888 | Jupyter                 |

Other ports are detected but listed as `tcp` protocol without preview URLs.

## Rate Limits

Preview URLs are rate-limited to **100 requests per minute** per port. This protects against abuse and ensures fair resource usage.

## HTTPS

All preview URLs use HTTPS with a wildcard certificate for `*.preview.caged.dev`. No configuration needed.

## Limitations

* Only TCP ports are detected (UDP is not scanned)
* Ports bound to `127.0.0.1` inside the sandbox are still accessible via preview URLs (the proxy connects internally)
* WebSocket connections are supported through the preview proxy
* Maximum of 20 exposed ports per sandbox