Tunnel Basics
Core concepts and the tunnel model used by rstream.
A tunnel is an endpoint in the rstream edge network that relays traffic to a target inside an environment. An agent runs next to the upstream service, establishes an outbound connection to the engine, and the engine forwards inbound traffic through that connection.
The project determines whether those entrypoints belong to one selected region or to the Global edge network. This choice applies to published and private protocols alike; it changes the available entrypoints and routing path, not the tunnel protocol. See Global and Regional Routing for the project model and agent region selection.
This section defines the terminology used throughout the tunnels documentation and explains the choices that shape tunnel behavior.
Components
A tunnel always involves three roles.
The agent is the process inside the private environment that initiates connectivity. In many setups the agent is the rstream CLI, but production systems often embed an SDK directly in an application or run a managed agent such as the Kubernetes operator tunnel agent.
The engine is the edge network entrypoint. It hosts tunnel endpoints, authenticates inbound traffic, applies access policies, and coordinates tunnel lifecycle.
The upstream is the service behind the tunnel. In the CLI workflow, upstream is typically a local host:port. When an SDK is embedded, upstream can also be an in-process handler.
Traffic direction
The term downstream refers to the client side of a connection, outside the environment. The term upstream refers to the private service side of a connection, inside the environment. These terms are protocol-agnostic and apply to HTTP, TLS, TCP, QUIC, and DTLS tunnels.
In HTTP tunnels, downstream and upstream are used to describe both protocol versions and authentication behavior: the engine accepts a downstream HTTP connection, then issues an upstream HTTP request toward the private service.
Tunnel type
rstream models two tunnel types.
A bytestream tunnel forwards a byte stream. It maps naturally to TCP-based traffic and is used for HTTP, TLS, and many private tunnels.
A datagram tunnel forwards packets. It is used for protocols that are message-oriented or UDP-based, and it is required for HTTP/3 in the rstream model. Datagram tunnels can carry raw DTLS or QUIC endpoints, HTTP/3 services such as WebTransport and MASQUE, or application protocols built on datagram transports such as SCTP.
Tunnel protocol
The tunnel protocol describes what the engine exposes on the public endpoint. The current protocol constants are http, tls, tcp, dtls, and quic. Some application protocols are carried inside these public protocols rather than appearing as separate tunnel protocol constants; for example WebSocket, WebTransport, CONNECT-UDP, and CONNECT-IP are HTTP tunnel behaviors.
Protocol availability depends on the engine edition, project plan, and enabled listeners. Community Edition supports HTTP and TLS tunnels, with optional ephemeral published TCP. Hosted and private runtimes can add reserved TCP addresses, DTLS, and QUIC listener support, with plan gates documented in Editions and Plans.
Published and private tunnels
Published tunnels expose an Internet-reachable endpoint on the edge network. Clients connect with standard tools such as browsers, curl, or protocol-native clients, and the engine can enforce edge authentication and access policies.
Published HTTP, TLS, DTLS, and QUIC tunnels can use an automatically allocated endpoint or a requested stable domain inside the project namespace. Published TCP tunnels use a hostname and port, allocated ephemerally or kept as a project reservation. Stable domains are covered in Stable Domains, and TCP addressing is covered in TCP Tunnels.
Private tunnels are not published publicly. They require an rstream dialer in a client application or SDK to connect. Private tunnels are useful for custom protocols, for fleet operations where endpoints must not be exposed publicly, and for workflows where the application controls connection behavior end-to-end.
Next steps
Private Tunnels covers unpublished tunnel access through rstream clients. Declarative Tunnels covers YAML, Docker labels, and Kubernetes operator workflows. Tunnel Transports covers the client-to-engine transport layer and its configuration. Tunnel Protocols covers the published protocol model, and HTTP Tunnels covers the most common published tunnel behavior.