---
title: Port Forwarding
description: "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
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
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
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