Skip to main content

​
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. 
curl https://api.caged.dev/v1/sandboxes/cage-a1b2c3d4/ports \
  -H "Authorization: Bearer caged_sk_..."
Response 200 OK 
[
  {
    "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

FieldTypeDescription
portintegerPort number
protocolstringhttp or tcp
preview_urlstringPublic URL (HTTP ports only)
protectedbooleanWhether password protection is enabled
detected_atstringWhen the port was first detected

​
Password-Protect a Port

Add password protection to a preview URL.
​
password
string
required
Password required to access the preview URL.
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 
{
  "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.