Skip to main content

​
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:
PortCommon Use
80HTTP
3000React, Next.js, Express
4200Angular
5173Vite
5000Flask
8000Django, FastAPI
8080General HTTP
8888Jupyter
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