Tunnel Transports

rstream separates two concerns: the public tunnel protocol exposed by the engine, and the transport used between an agent and the engine. The tunnel protocol describes the traffic served to downstream clients. The tunnel transport describes how the agent reaches the edge network.

This separation makes tunnel behavior predictable. An application can expose HTTP or datagram traffic while using the same hardened transport layer to reach the engine.

Transport protocols

The current rstream client transport implementations support TLS and QUIC for agent-to-engine connectivity.

TLS transport uses a direct TCP connection to the edge and negotiates the rstream session inside TLS 1.3. QUIC transport uses a single QUIC connection to the edge and multiplexes client activity over QUIC streams and datagrams where appropriate.

QUIC typically provides better behavior on unstable networks and for datagram-heavy workloads. TLS remains the most broadly compatible path and is less likely to be blocked in restrictive environments.

Security model

Transport settings do not change the cryptographic baseline. The client-to-edge session is always established with a modern TLS 1.3 security model, whether the transport path uses TLS over TCP or QUIC.

Transport configuration only changes the network path used to reach the edge. Proxy settings, deterministic egress, DNS override, or QUIC transport selection do not weaken published tunnel policies or tunnel transport admission.

Transport configuration

The CLI configuration file and SDKs support transport configuration that affects how the agent reaches the engine. This includes binding to a specific local address or network interface, forcing IPv4 or IPv6, overriding DNS resolution for engine hostname lookup, enabling multipath TCP when supported by the host, routing through an HTTP CONNECT proxy with optional proxy authentication, and selecting QUIC as the tunnel transport where supported.

These settings are configured in the CLI context or through SDK transport options. The transport block supports bind, ipFamily, dns, mptcp, proxy, and useQuic.

A context transport example looks like this:

transport:
  ipFamily: ipv4
  useQuic: true
  dns:
    override: "1.1.1.1:853"
    tls: true
    serverName: "cloudflare-dns.com"
    dnssec: true
  proxy:
    http: "http://proxy.local:3128"

Environment entries in the configuration file and context-scoped overrides use the same shape. The effective transport is the environment transport merged with the context transport, with explicit override values taking precedence.

DNS resolution and ECH discovery

Advanced DNS options affect both direct hostname resolution and ECH discovery.

When a DNS override is enabled, the same resolver path is used for edge hostname resolution and for discovery of DNS SVCB and HTTPS records carrying ECH configuration. This keeps ECH discovery aligned with the same ALPN and target host logic used by modern browsers.

The DNS transport options are:

• dns.override — use a specific resolver address, such as 1.1.1.1:53 or 1.1.1.1:853.
• dns.tls — use DNS over TLS for these queries. When the override omits a port, rstream defaults to 853.
• dns.serverName — set the TLS server name used for DNS over TLS. This is required when the override is an IP address.
• dns.dnssec — require authenticated DNSSEC answers from the resolver.

Without these options, the client uses the platform resolver configuration for both direct hostname resolution and ECH discovery. On macOS, scoped per-domain resolvers are respected. On Unix-like systems, the resolver fallback follows the system resolver configuration.

QUIC tunnel transport

QUIC transport changes only the client-to-edge session. It is independent from the public tunnel protocol. A project can publish HTTP, TLS, DTLS, or QUIC endpoints while the publishing client uses QUIC to reach the edge.

QUIC transport can be selected persistently with the useQuic transport key. Go SDK processes that use config.NewClientFromEnv() can also opt in with RSTREAM_QUIC_TRANSPORT=1. SDKs can select the corresponding QUIC transport type directly when building a client in code.

QUIC transport accepts the same address-family and advanced DNS settings as the default TLS transport. HTTP CONNECT proxy support remains specific to the TCP transport path.

Do not confuse QUIC tunnel transport with published QUIC tunnels. The transport setting changes how the rstream client reaches the engine. A published QUIC tunnel changes what downstream clients connect to at the edge.

Published and private tunnels

For published tunnels, transport configuration primarily concerns the publishing client that maintains the upstream session to the edge. Downstream users connect with standard clients and do not use rstream transport settings.

For private tunnels, transport configuration can matter on both sides. The publishing client must maintain its upstream session, and any rstream client dialing the private tunnel must also establish its own session to the edge under its own network constraints.