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

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

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:

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