Skip to main content
GET
Open a TCP tunnel WebSocket
Open an authenticated WebSocket tunnel to a TCP port listening inside the sandbox. Use this endpoint when you need raw TCP byte forwarding, such as VNC, Postgres, Redis, or Chrome DevTools over a private local tunnel. For most users, the tl sbx tunnel CLI or SDK helper manages this protocol for you.

Endpoint

Use the WebSocket endpoint on the sandbox proxy host:

Example Connection

Authenticate to the sandbox proxy with your API key. The proxy injects the internal forwarded-auth headers that the daemon requires.

WebSocket Protocol

After the WebSocket upgrade succeeds, binary frames are relayed verbatim:
  • Client binary frames are written to 127.0.0.1:<port> inside the sandbox.
  • Bytes read from that TCP connection are sent back as WebSocket binary frames.
  • Text frames are rejected.

Response Semantics

  • 101 Switching Protocols means the tunnel is open.
  • 400 Bad Request means port is missing, invalid, or 0.
  • 401 Unauthorized means authenticated sandbox-proxy forwarding was not present.
  • 502 Bad Gateway means nothing accepted the TCP connection on 127.0.0.1:<port> inside the sandbox.
For local-port forwarding examples, see Local Tunnels.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

port
integer
required

Sandbox-local TCP port to connect to on 127.0.0.1.

Required range: 1 <= x <= 65535

Response

WebSocket upgrade successful