Skip to main content
The Port Forwarding API allows you to expose container ports for browser access or local tunneling.

​
Overview

Rexec supports two forwarding modes:
  • HTTP Proxy: Access container services via browser at /p/:forwardId/
  • WebSocket Tunnel: Binary tunnel for non-HTTP protocols (SSH, databases, etc.)
Port forwards are tied to container lifecycle and deleted when the container stops.

​
Create port forward

POST /api/containers/:containerId/port-forwards Create a new port forward.
​
container_port
integer
required
Port inside container (1-65535)
​
local_port
integer
Port on Rexec host (auto-assigned if omitted)
​
name
string
Friendly name for this forward
curl
curl -X POST https://api.rexec.sh/api/containers/cont_123/port-forwards \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "container_port": 8080,
    "name": "Web Server"
  }'
​
id
string
Port forward ID
​
container_port
integer
Port inside container
​
local_port
integer
Assigned port on host
​
proxy_url
string
HTTP proxy URL: https://api.rexec.sh/p/{id}/
​
websocket_url
string
WebSocket tunnel URL: wss://api.rexec.sh/ws/port-forward/{id}
​
name
string
Forward name
​
created_at
string
ISO timestamp

​
List port forwards

GET /api/containers/:containerId/port-forwards List all forwards for a container.
curl
curl https://api.rexec.sh/api/containers/cont_123/port-forwards \
  -H "Authorization: Bearer YOUR_TOKEN"
Returns array of port forward objects.

​
Delete port forward

DELETE /api/containers/:containerId/port-forwards/:forwardId Close and remove a port forward.
curl
curl -X DELETE https://api.rexec.sh/api/containers/cont_123/port-forwards/pf_456 \
  -H "Authorization: Bearer YOUR_TOKEN"

​
HTTP proxy access

Access HTTP services via the proxy URL: 
curl https://api.rexec.sh/p/pf_456/api/health
  • Preserves paths, query strings, and headers
  • Supports WebSocket upgrades
  • Authenticated (requires valid session)
Use this for web apps, APIs, and dashboards running in containers.

​
WebSocket tunnel

For non-HTTP protocols (databases, SSH, etc.), use the WebSocket tunnel: 
const ws = new WebSocket('wss://api.rexec.sh/ws/port-forward/pf_456', [
  'Bearer', 'YOUR_TOKEN'
]);

ws.binaryType = 'arraybuffer';

ws.onopen = () => {
  // Send data to container port
  ws.send(new TextEncoder().encode('GET / HTTP/1.1\r\n\r\n'));
};

ws.onmessage = (event) => {
  // Receive data from container
  console.log(new TextDecoder().decode(event.data));
};
WebSocket tunnels have 5-minute idle timeout. Send periodic pings to keep alive.

​
Use cases

​
Web application preview

# Inside container: run web server on port 3000
npm run dev

# Create forward
curl -X POST https://api.rexec.sh/api/containers/cont_123/port-forwards \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"container_port": 3000, "name": "Next.js App"}'

# Response includes proxy_url:
# https://api.rexec.sh/p/pf_abc123/

# Access in browser:
open https://api.rexec.sh/p/pf_abc123/

​
Database access

# Forward PostgreSQL port
curl -X POST https://api.rexec.sh/api/containers/cont_123/port-forwards \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"container_port": 5432}'

# Use WebSocket tunnel client (like wscat or custom script)
# to connect local psql to container database

​
Limitations

  • Maximum 10 forwards per container
  • Forwards are deleted when container stops
  • HTTP proxy has 100MB request/response limit
  • WebSocket tunnel has 10MB/s throughput limit
  • Pro/Enterprise tiers support custom domains

​
Error codes

CodeMessageDescription
400Invalid portPort must be 1-65535
403Port already forwardedDuplicate container_port
404Container not foundInvalid container ID
409Container not runningMust be in running state
429Limit exceededMax 10 forwards per container

Build docs developers (and LLMs) love

Get started for freeTalk to us