Local Tunnels

Tunnels give your machine a localhost:<port> that maps directly to a port inside a running sandbox. The relay travels over a WebSocket through the sandbox proxy, so your TensorLake credentials authenticate every connection — you do not need to add the port to exposed_ports or make it public. Reach for a tunnel when you need a raw TCP connection into a sandbox. The sandbox proxy at *.sandbox.tensorlake.ai only speaks HTTP, WebSocket, gRPC, and SSH. Anything else — VNC’s RFB protocol, the Postgres wire protocol, MySQL, Redis’s RESP, MongoDB, custom binary protocols — needs a tunnel because the proxy cannot frame those bytes for you. You can also use a tunnel for HTTP/WS/gRPC traffic when you would rather keep the port private to your laptop than expose it through the public sandbox URL. Driving Chrome’s DevTools Protocol from your laptop is a typical case: CDP is WebSocket, so the proxy could carry it, but a tunnel keeps the debugger reachable only at 127.0.0.1 and skips the per-port exposed_ports configuration. Tunnels and exposed ports are independent. A tunnel works even when the port is not in exposed_ports.

Open a Tunnel

The simplest way is the CLI. Pick any local port (defaults to the same number as the remote port) and leave the command running.

CLI
JavaScript
Python

tl sbx tunnel <sandbox-id-or-name> 5901 --listen-port 15901

The command keeps running and prints connection events. Press Ctrl+C to stop the tunnel; the sandbox keeps running.Without --listen-port, the local port matches the remote port:

tl sbx tunnel <sandbox-id-or-name> 9222

import { Sandbox } from "tensorlake";

const sandbox = await Sandbox.connect({ sandboxId: "<sandbox-id>" });
const tunnel = await sandbox.createTunnel(5901, { localPort: 15901 });

const { host, port } = tunnel.address();
console.log(`tunnel listening on ${host}:${port}`);

// ... use it ...

await tunnel.close();

createTunnel(remotePort, options) returns a TcpTunnel. Useful options:

localHost — bind interface (defaults to 127.0.0.1).
localPort — local port number; pass 0 for an ephemeral port and read it back from tunnel.address().
connectTimeout — seconds to wait for each WebSocket connection (defaults to 10).

The Python SDK does not yet ship a native tunnel helper. Drive the CLI from a subprocess:

import subprocess

tunnel = subprocess.Popen(
    ["tl", "sbx", "tunnel", "<sandbox-id>", "9222", "-l", "9222"],
)
try:
    # Use http://127.0.0.1:9222 from your code.
    ...
finally:
    tunnel.terminate()
    tunnel.wait()

The local listener is per-process. If you want two clients to share one tunnel, run the CLI once and connect both clients to the same localhost:<port>.

How It Works

The CLI and the TypeScript SDK both speak the same protocol:

A WebSocket is opened to the sandbox proxy, carrying your API key, PAT, or session cookie.
The proxy authorizes the request, finds the dataplane that owns the sandbox, and pipes bytes to 127.0.0.1:<remote-port> inside the sandbox.
The local TCP listener accepts a connection from your client and relays bytes both ways across the WebSocket.

Because every byte rides on an authenticated WebSocket, the remote port stays private to your account — there is no public hostname for it.

Common Patterns

Inside the sandbox	Local port	Client
`5901` (TigerVNC)	`15901`	macOS Screen Sharing, RealVNC, TigerVNC, Remmina
`9222` (Chrome DevTools Protocol)	`9222`	Playwright `connect_over_cdp`, Puppeteer, `chrome-remote-interface`
`5432` (Postgres)	`5432`	`psql`, DBeaver, TablePlus
`3000` (dev server)	`3000`	Browser at `http://localhost:3000`

Tunneling is also the easiest way to reach the sandbox’s authenticated Computer Use VNC port from a desktop client without polling screenshots.

Troubleshooting

Connection refused from the local end. The remote service inside the sandbox is not listening on the port yet. Tail its logs (tl sbx exec <id> -- bash -lc 'ss -ltnp') and retry.
502 Bad Gateway during handshake. The sandbox has not finished booting the workload. Wait a few seconds and reconnect; the proxy returns 502 when nothing is listening on the remote port.
WebSocket auth failures. Confirm tl whoami shows the right organization and project, or that TENSORLAKE_API_KEY is set in the shell that runs the CLI.

Overview

Guides

Use Cases

Open a Tunnel

How It Works

Common Patterns

Troubleshooting

Overview

Guides

Use Cases

Documentation Index

​Open a Tunnel

​How It Works

​Common Patterns

​Troubleshooting

Open a Tunnel

How It Works

Common Patterns

Troubleshooting