Tunnel Basics

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.

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 daemon.

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, 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.

Tunnel protocol

The tunnel protocol describes what the engine exposes on the public endpoint. The current protocol constants are http, tls, dtls, and quic.

Protocol availability depends on the engine edition and the enabled listeners.

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.

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

HTTP Tunnels covers the most common published tunnel behavior. Tunnel Protocols covers non-HTTP protocol behavior. Tunnel Transports covers the agent-to-engine transport layer and its configuration.