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

Field	Type	Description
`port`	integer	Port number
`protocol`	string	`http` or `tcp`
`preview_url`	string	Public URL (HTTP ports only)
`protected`	boolean	Whether password protection is enabled
`detected_at`	string	When the port was first detected

Password-Protect a Port

Add password protection to a preview URL.

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

Caged scans /proc/net/tcp inside the sandbox every 2 seconds
New listening ports are registered in the port registry
HTTP ports (80, 3000, 4200, 5173, 8000, 8080, etc.) get public preview URLs
Non-HTTP ports (databases, etc.) are listed but not publicly exposed
Ports are removed when they stop listening

Rate Limits

Preview URLs are rate-limited to 100 requests per minute per port.

Was this page helpful?