rstream-go

rstream-go is the Go SDK for rstream, a secure connectivity platform built around a globally distributed edge network and lightweight agents. Agents maintain outbound-only tunnels from local and private environments, while the edge network authenticates traffic, enforces access policy, and routes requests to upstream services. rstream supports HTTP and non-HTTP workloads and provides end-to-end visibility through connection logs and metrics.

The Go SDK is the reference implementation. It covers the broadest rstream API surface and is the most complete SDK in terms of protocol support and tunnel lifecycle features. The rstream CLI is implemented in Go and lives in this repository, so the SDK and CLI share the same configuration model and operational behavior.

Looking for native integration? The C++ SDK is available at https://github.com/rstreamlabs/rstream-cpp.

What is a tunnel?

A tunnel is a secure way to expose services without requiring inbound ports, public IPs, or NAT changes. In rstream, tunnels are established outbound to the edge network, reducing exposure while keeping access controllable and observable.

When you create a published tunnel with rstream, you get a forwarding address that routes inbound traffic to a local service. For example, a tunnel for localhost:8080 provides a forwarding address like https://abc123.rstream.io that forwards HTTP requests to local port 8080.

How rstream works

rstream establishes outbound tunnels between environments running services or devices and the rstream edge network. Clients connect to the edge using a forwarding address for published tunnels or a tunnel identifier for private tunnels. The edge authenticates the connection, applies policy, and forwards traffic through the existing tunnel path to the upstream service.

Tunnel transports are encrypted, and edge enforcement decisions are surfaced through logs and metrics.

Tunnel types

rstream supports two fundamental tunnel types:

Bytestream tunnels (TCP-like) provide reliable, ordered transmission for protocols such as HTTP and TLS, as well as custom bytestream services.

Datagram tunnels (UDP-like) provide low-latency, message-oriented communication for protocols such as QUIC and DTLS, as well as custom datagram services.

Published vs private tunnels

Published tunnels are accessible via standard clients (browsers, curl, etc.) through forwarding addresses. Published tunnels can be configured with edge authentication and access policies depending on protocol and deployment.

Private tunnels require an rstream client to connect. Private tunnels are accessed by name (if specified) or by ID through the rstream dialer instead of a public forwarding address.

Use cases

Local development: Expose a local service for testing, demos, and collaboration without changing network configuration.

Fleet operations: Provide controlled access to devices and machines across environments with consistent identity, policy, and observability.

Infrastructure and platforms: Use rstream as a connectivity layer for internal tools, CI workflows, and production access paths.

Generative AI workflows: Distribute work across fleets of runners or machines while keeping access scoped and auditable.

Real-time systems: Support low-latency traffic patterns for telemetry, streaming, and datagram workloads.

Supported features

Core tunneling: Create tunnels for TCP-like and UDP-like workloads with outbound-only connectivity.

Multi-protocol support: HTTP (1.1, 2, 3), TLS, DTLS, QUIC, plus WebSocket and WebTransport in HTTP tunnels.

Access control: IP restrictions, GeoIP policies, mutual TLS, token-based access, and account-based access depending on tunnel configuration.

Operational visibility: Connection logs and metrics for traffic, enforcement decisions, and performance signals.

Transport configuration: IPv4/IPv6 selection, DNS override, interface binding, HTTP CONNECT proxy support, SOCKS5 proxy support, and MASQUE proxy support for QUIC transport.

Resilience: Long-lived agents, reconnect behavior, and transport-level multiplexing for stable connectivity.

Control-channel liveness and payload lifetime are intentionally separate. A negotiated heartbeat grace absorbs short network interruptions. If that grace expires, the listener stops admitting new streams and reconnects, while already accepted byte streams and registered QUIC datagram channels remain usable until the application closes them or the data path itself ends. Explicit tunnel, control-channel, client or process shutdown still closes owned sessions. SDK callers therefore retain normal ownership of every connection returned by Accept; they must close it even if ControlChannel.Done reports a transport failure.

Supported protocols

HTTP protocols: HTTP/1.1, HTTP/2 (H2C), HTTP/3 with WebSocket and WebTransport support.

Secure transports: TLS- and QUIC-based transports for agent-to-edge connectivity, plus DTLS and QUIC as published tunnel protocols when enabled by the deployment.

Network options: IPv4/IPv6, MPTCP, HTTP CONNECT, SOCKS5, MASQUE CONNECT-UDP for QUIC transport, and custom DNS resolution.

Compatibility

rstream is compatible with Linux, macOS 13 or newer, and Windows. Additionally, rstream supports other UNIX systems such as FreeBSD, OpenBSD and NetBSD through manual installation.

FIPS 140-3 profile

rstream-go provides a restricted FIPS 140-3 build profile for reviewed Linux client deployments. The FIPS SDK and CLI artifacts embed and use the NIST CMVP-validated Go Cryptographic Module, certificate 5247, which has Overall Security Level 1. They pin that module and the reviewed quic-go and webtransport-go versions, run the module in its approved mode, and fail closed when an excluded transport, protocol, or runtime configuration is requested.

The applicable artifact claim is FIPS 140-3 Inside — Go Cryptographic Module, Certificate #5247 (Overall Security Level 1). The level and certificate apply to the embedded Go cryptographic module; the complete rstream product has not undergone a separate CMVP module validation. This is a distinct build from the standard multi-protocol distribution.

The profile supports TLS/mTLS, direct QUIC, ordinary HTTP/3, and authenticated E2E WebTTY over WebTransport. WebTTY uses a P-256/HKDF-SHA256/AES-256-GCM random-nonce protocol profile; the standard build can use either this profile or the legacy X25519 profile, while the FIPS build accepts only the former.

See docs/010-fips-140-3-profile.md for the supported boundary, exclusions, build procedure, runtime evidence, and module upgrade process.

Installation (rstream CLI)

The installation paths in this section install the rstream CLI binary and its runtime dependencies. They do not install the Go SDK as a library dependency.

Local build

To build the CLI locally from this repository on the current platform, run:

make

Debian/Ubuntu

For Debian-based distributions, the installer deploys packaged CLI binaries and dependencies:

sudo /bin/bash -i -c "$(curl -fsSL https://rstream.io/scripts/install-debian.sh)"

macOS

On macOS, the Homebrew tap provides the standard CLI installation path:

brew tap rstreamlabs/rstream && brew install rstream

Windows

On Windows, install rstream from the official WinGet Community Repository:

winget install --id rstream.rstream --exact --source winget

If winget is not available, or a new stable release has not reached the Community Repository yet, use the PowerShell installer:

& { Invoke-Expression ([System.Text.Encoding]::UTF8.GetString((Invoke-WebRequest -Uri 'https://rstream.io/scripts/install.ps1' -UseBasicParsing).Content)) }

Manual installation

For generic environments, use the manual installer script for the CLI binary:

/bin/bash -i -c "$(curl -fsSL https://rstream.io/scripts/install.sh)"

Docker

If you run the CLI in containers, pull the public image:

docker pull rstream/rstream:latest

Authentication

The standard developer-machine path is browser-based login:

rstream login

This uses OAuth 2.0 Device Authorization Grant by default. The legacy rstream login flow remains available for compatibility checks with rstream login --auth-flow legacy.

If this is a new rstream account, the browser step opened by rstream login is also where the user signs up or signs in and approves CLI access.

Codex can start the same flow through local MCP after rstream codex setup: rstream_auth_start returns the approval URL, and rstream_auth_poll stores the approved token locally without returning it to the prompt. The approval code is only returned separately when the provider cannot embed it in the URL. The default MCP login scope is limited; when the user explicitly asks Codex to create projects or change project settings, rstream_auth_start can request a broader permissions array and the hosted approval page shows that elevated grant.

For advanced authentication modes (token-based login, remote device flows, and project-scoped contexts), see docs/001-cli-workflow.md.

Before running SDK examples, ensure a project context is set up with the CLI (rstream project use <project-endpoint>). The SDK and CLI share the same configuration model and config file.

For agent and CI checks, run:

rstream doctor -o json

The diagnostic output covers config, context, token claims, Control plane API authentication, project resolution, DNS, TLS, and engine inventory without printing secrets.

Environment variables