Skip to content

How it works

Understand how the publisher, relay, target service and caller work together.

Publisher and relay

The publisher is the CLI process on a machine that can reach your target service. It authenticates to the Tubu relay with an API key and registers the domains in its configuration over a secure WebSocket connection.

When a caller connects, the relay asks the publisher to open a data channel. The publisher connects to the target from its own network. Target hostnames are resolved on the publisher machine.

HTTP request path

HTTP request path
  1. Browser or HTTP client
  2. Public HTTPS endpoint
  3. Tubu relay
  4. Publisher CLI
  5. Local HTTP service

A browser connects to the public HTTPS domain. Public TLS ends at Tubu infrastructure. The relay forwards the request through the publisher connection, and the CLI sends it to the selected HTTP or HTTPS target.

The longest matching route prefix selects the target. Its rewrite rules then change the pathname. The CLI sets the Host header to the target host and port. For an HTTPS target it also uses the target hostname for TLS and validates its certificate.

WebSocket upgrades and SSE follow the HTTP tunnel. Their long lived connections need both the publisher and target to remain available.

TCP connection path

TCP connection path
  1. SSH or database client
  2. Local tubu forward listener
  3. Tubu relay over WSS
  4. Publisher CLI
  5. TCP service

The publisher runs npx tubu-cli tcp near the service. The caller runs npx tubu-cli forward on the machine where the SSH or database client runs. That command listens on an IPv4 loopback port and opens a secure WebSocket for each local connection.

The application connects to that local port. Tubu transports the TCP bytes through the relay to the publisher and target. The caller does not supply a Tubu API key. SSH or database authentication remains the responsibility of the target service.

Authentication and encryption

The API key authorizes publishing and domain reservation. An HTTP shared secret controls access to public requests through the X-Tubu-Auth header. These credentials have different purposes.

The publisher connection and public HTTPS connection use TLS. The final connection from the publisher to an HTTP target is unencrypted; use an HTTPS target when that hop needs TLS. TCP application encryption, such as SSH or database TLS, is separate from Tubu transport encryption.

Protect an HTTP tunnel explains how to require a shared secret. TCP tunnels use the target protocol for authentication.

Lifecycle and limits

Configuration files are read once at startup. Restart the publisher after a change. A disconnected publisher exits with an error; it does not reconnect automatically. Interrupted application sessions are not replayed.

Account limits apply to active tunnels, reserved domains and monthly traffic. Upload and download count toward traffic. Quota exhaustion closes tunnels and blocks new tunnels until the quota resets or increases. Check current limits in your account.