Logo
Stable Domains

Stable Domains

Use stable public domains for published tunnels.

Written by uartnet

@uartnet

Published tunnels receive a public hostname on the engine. When no hostname is requested, the engine allocates a standard endpoint under the tunnel namespace.

Stable domains let a tunnel request a predictable hostname inside the project namespace. This is useful when a service URL is referenced by webhooks, callbacks, mobile apps, or external systems that should not track a new generated URL after every reconnect.

Domain shape

Each project has a project endpoint. If the project endpoint is f587ee53 and the engine host is aws-eu-west-3-1.c.rstream.io, requested stable domains must live under:

<slug>-f587ee53.t.aws-eu-west-3-1.c.rstream.io

The slug identifies the service inside the project, for example:

api-f587ee53.t.aws-eu-west-3-1.c.rstream.io
admin-f587ee53.t.aws-eu-west-3-1.c.rstream.io

The engine rejects hostnames outside the project namespace and hostnames already used by another live tunnel.

CLI usage

Use --host when creating a tunnel:

rstream forward 8080 --host api-f587ee53.t.aws-eu-west-3-1.c.rstream.io

For rstream forward, rstream run, and WebTTY server flows, the CLI also generates and reuses a stable domain during reconnect or tunnel recreation when no hostname was provided by the user. Explicit --host remains the durable choice when the same public URL must survive process restarts or config redeployments.

Runtime fields

Tunnel properties expose the public endpoint through hostname and port.

The older host field is still returned for compatibility with existing clients, but it is server-managed and should be treated as deprecated. New integrations should read hostname and port, and should set hostname when they want to request a stable domain.

Declarative configuration

YAML and Docker-label configuration use the same hostname model.

version: 1
tunnels:
  - name: api
    forward: 8080
    tunnel:
      publish: true
      protocol: http
      host: api-f587ee53.t.aws-eu-west-3-1.c.rstream.io

For Docker labels:

labels:
  rstream.tunnel.api.forward: "8080"
  rstream.tunnel.api.publish: "true"
  rstream.tunnel.api.protocol: "http"
  rstream.tunnel.api.host: "api-f587ee53.t.aws-eu-west-3-1.c.rstream.io"

The configuration key is named host for CLI ergonomics, but it maps to the tunnel hostname property sent to the engine.

Tunnel BasicsHTTP Tunnels