Global and Regional Routing

A project is either regional or Global. A regional project stays attached to one region. A Global project can use every region available in its edge network.

Basic projects use a regional location, with the nearest available region recommended during creation. Pro and Enterprise projects can use Global when an edge network is available, or select a regional location when data locality and a fixed operating region are preferred.

Global and regional projects

A regional project exposes one regional endpoint. Agent control channels and tunnel endpoints remain in that region. The endpoint can be served by a pool of engines without attaching the project to one engine instance.

A Global project exposes a common edge endpoint and regional endpoints. The common endpoint directs a connection to an available nearby region. An agent can still select one of the project's regions explicitly when its control channel must open there.

Global routing preserves the behavior of published HTTP, TLS, QUIC, DTLS, and TCP tunnels, private byte-stream and datagram tunnels, and managed WebTTY sessions. The selected scope changes where a connection enters the edge; it does not change the tunnel protocol or its security and delivery semantics.

Managed TURN follows the same regional or Global scope without entering the tunnel routing path. Credentials for a regional project advertise its regional TURN service. Credentials for a Global project advertise the common TURN endpoint, which directs allocations to an available region.

Selecting an agent region

The project list exposes the routing scope and available regions:

rstream project list

The ROUTING column distinguishes Global and regional projects. REGIONS lists the regions that a Global project accepts and the fixed region of a regional project.

Without an explicit region, the CLI uses the engine endpoint resolved for the project. On a Global project, --region selects one of the regional endpoints returned by the control plane:

rstream --region eu-west-3 forward 22 --tcp

The same selection can be stored as region in the active context or provided through RSTREAM_REGION. A requested region must belong to the selected project. An explicit region cannot be combined with an explicit engine override because the two options would define competing destinations.

Selecting an agent region does not constrain where a Global public connection enters the edge network. The region where the agent opens its control channel is the owner region. The region that accepts a downstream connection is the ingress region.

When a tunnel opens, the CLI reports the owner region selected for its control channel. That value is not necessarily the ingress region later chosen for a downstream connection.

SDKs that do not query the control plane can still connect to a known regional engine address directly. This is a low-level engine override: the caller supplies the address, and the engine validates that the project is authorized in that region.

Routing paths

When ingress and owner differ, rstream can establish the connection through Direct or Cross-region routing. Direct routing is the default. The owner uses the existing control channel to instruct the agent to open a dedicated stream to ingress. Application traffic then travels between ingress and the agent without passing through the owner.

                     control channel
Agent <===========================================> Owner engine
  ^                                                     |
  |                 connection instruction              |
  +-----------------------------------------------------+
  |
  +<========== direct stream ==========> Ingress engine <====> Downstream

Cross-region routing adds the owner to the application data path when ingress and owner are in different regions. It can be useful when the deployment provides a preferred inter-region network, but it is never selected between engines in the same region.

Agent <====> Owner engine <==== inter-region route ====> Ingress engine <====> Downstream

Published tunnels created by the CLI can allow this path with the protocol-independent routing option:

rstream forward 8080 --allow-cross-region-routing

This option permits the edge to carry a stream between regions when the ingress and owner differ. It does not require an inter-region path: same-region traffic always uses Direct routing, and Direct remains the fallback when a Cross-region setup cannot be established.

Connection logs report the path actually used, rather than the requested policy. They identify the ingress and owner engines and regions so the route remains observable for each connection.