Private Tunnels

A private tunnel is a tunnel that is not published as an Internet-reachable endpoint. The engine still maintains tunnel state and forwards traffic, but connections require an rstream client or SDK that can dial the tunnel directly by id or name.

Private tunnels are useful when a service should remain reachable only through rstream-aware clients, when the upstream protocol should not be exposed as a public endpoint, or when the application needs direct control over connection behavior such as retries, timeouts, and multiplexing. Both sides still use outbound sessions to the engine, so the private environment does not need inbound firewall openings.

The model is intentionally different from a hidden public hostname. A private tunnel has no standard Internet socket for browsers, SSH clients, or custom clients to discover. Access happens through the rstream runtime, which means authentication, project selection, resources.tunnels boundaries, and the selected tunnel transport are part of the connection path.

Creating a private tunnel

In the CLI, private tunnels are created by disabling publishing. A name is optional, but it is usually useful because clients can dial the name instead of copying a generated tunnel id.

rstream forward 8080 --no-publish --name internal-api

Private bytestream tunnels are the default. Datagram semantics can be selected when the private workload is UDP-like and the client uses the packet dialing API.

rstream forward 5300 --datagram --no-publish --name internal-dns

In the engine model, private tunnels reject public exposure options such as HTTP version configuration and edge HTTP authentication settings. The tunnel remains accessible through rstream dialing APIs.

Connecting to a private tunnel

Private tunnels are dialed by tunnel id or name from an SDK client. Bytestream tunnels use Dial in the Go SDK:

conn, err := client.Dial(ctx, rstream.Addr{IdOrName: "internal-api"})

Datagram tunnels use the packet API:

pc, err := client.PacketDial(ctx, rstream.Addr{IdOrName: "internal-dns"})

Netcat over rstream

The CLI includes a netcat-style utility for private bytestream sessions. The command is available as rstream netcat, rstream ncat, and rstream nc.

rstrm://<name-or-id> selects a private rstream endpoint. In listen mode, rstream nc can create a private unpublished tunnel and proxy it to a local service:

rstream nc -L rstrm://ssh-server -R 127.0.0.1:22

A client can then connect to that private tunnel:

rstream nc rstrm://ssh-server

The same command is useful as an SSH ProxyCommand because SSH still performs its normal host-key verification and user authentication while rstream carries the TCP stream:

ssh -o 'ProxyCommand rstream nc rstrm://ssh-server' admin@ssh-server hostname

The same local TCP adapter pattern works for database tooling. Access a Private PostgreSQL Database Without a VPN using rstream shows a private PostgreSQL workflow using rstream nc, a local client port, and standard PostgreSQL URLs.

SSH as a motivating example

SSH is a common example of a protocol that is not exposed as a first-class published tunnel endpoint. A private tunnel allows the SSH client to remain local while the rstream dialer carries traffic to the private environment.

A complete walkthrough for SSH, including ProxyCommand, rstream nc, and rstream run, is available in Access Remote Machines over SSH with rstream.

Transport and security notes

For private tunnels, transport configuration matters on both sides. The publishing client must maintain its outbound session to the engine, and each dialing client must also reach the engine under its own network constraints. Proxy settings, DNS override, address-family selection, and QUIC transport are documented in Tunnel Transports.

Private tunnels do not use public HTTP edge authentication because there is no public HTTP request path. Runtime access is controlled by the token or credential used by the dialing client and by any resources.tunnels boundaries attached to that credential. Project policies that forbid public tunnels still allow private tunnels when the project plan and token permissions allow tunnel creation.