Port Forwarding

Port forwarding lets you expose services running inside a VM to the internet. When your sandbox runs a web server, API, or any TCP service, port forwarding creates a public endpoint that routes traffic to the guest VM.

How It Works

Port forwarding uses DNAT (Destination Network Address Translation) rules on the compute node. When you create a port forward, the system:

Allocates a random high port on the compute node's public IP
Creates a DNAT rule that routes traffic from host:port → guest_vm:guest_port
Returns the hostname and port for external access

Text

Internet → compute-node:38492 → DNAT → guest-vm:3000

Creating a Port Forward

The VM must be running to create a port forward:

Bash

curl -X POST https://api.firecase.ai/instances/{id}/port-forwards \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "guest_port": 3000,
    "protocol": "tcp",
    "label": "dev-server"
  }'

Response:

JSON

{
  "port_forward": {
    "id": "...",
    "instance_id": "...",
    "guest_port": 3000,
    "host_port": 38492,
    "protocol": "tcp",
    "label": "dev-server"
  },
  "hostname": "compute-1.firecase.ai"
}

Your service is now accessible at compute-1.firecase.ai:38492.

Listing Port Forwards

Bash

curl https://api.firecase.ai/instances/{id}/port-forwards \
  -H "Authorization: Bearer $API_KEY"

Deleting a Port Forward

Bash

curl -X DELETE https://api.firecase.ai/instances/{id}/port-forwards/{forward_id} \
  -H "Authorization: Bearer $API_KEY"

Restrictions

Protocol: Only tcp is supported currently
Blocked ports: Port 22 cannot be forwarded (use SSH forwarding instead)
Privileged ports: Ports below 1024 require admin permissions
Quota: The number of forwards is limited by the instance's profile (max_forwarded_ports, default: 5)
Lifecycle: Port forwards are tied to the VM session. When the VM stops, the DNAT rules are cleaned up.

Use Cases

Web development: Forward port 3000/8080 to preview a dev server
API testing: Expose a service for webhook callbacks
Database access: Forward a database port for external tooling
Demo sharing: Give someone a URL to your running application

Next Steps

See the Port Forwards API for all operations
Learn about SSH access for direct shell connections
Follow the Dev Environments guide for full setup patterns

Checkpoints