Custom Domains

Custom domains let a project publish HTTP, TLS, QUIC, and DTLS tunnels on a hostname outside the namespace owned by rstream. A registered hostname remains attached to the project while tunnels using it connect and disconnect.

The feature is available to Pro and Enterprise projects.

A project may register up to 50 custom hostnames.

This is different from a stable domain, which remains inside the engine namespace and requires no customer DNS configuration. A custom domain requires ownership verification, traffic routing, and a managed certificate when rstream terminates TLS.

Register a hostname

A registered hostname covers one DNS name, such as api.example.com. Add it from the project dashboard, then publish the DNS records shown there. The records are generated from the selected cluster and should be copied exactly.

rstream currently supports individual hostnames. Wildcard hostnames require DNS-01 certificate validation, which is not supported yet.

DNS configuration

The dashboard presents each required DNS record separately. Ownership is verified with a TXT record under _rstream-verify. Traffic is routed with a CNAME, or with an apex-compatible ALIAS, ANAME, or flattening record, targeting the cluster ingress.

Hosted custom hostnames use ACME TLS-ALPN-01. The certificate authority validates the hostname through public TCP port 443 after its traffic record points to the engine. No additional ACME DNS record is required.

The hostname becomes DNS-verified only after the ownership and traffic records resolve correctly. Certificate readiness is reported separately because DNS propagation may complete before certificate issuance.

Certificate status

After DNS verification, the control plane asks the project engine to provision the certificate. A private or temporarily offline engine performs the same work when a tunnel first uses the hostname, so certificate readiness does not depend on the engine being reachable from the dashboard. The engine also reconciles verified hostnames independently, which recovers issuance after a missed request.

The dashboard reports this lifecycle as pending, provisioning, ready, renewing, or failed. It refreshes transient states automatically and shows issuance and expiry dates when a certificate is available.

A valid certificate remains available while renewal is in progress. If issuance or renewal fails, the dashboard reports the issue and the engine retries automatically. An existing certificate continues to serve traffic until it expires. A failed initial issuance does not make a TLS-terminated tunnel available until a later attempt succeeds.

Publishing a tunnel

Once an individual hostname is verified and its certificate is ready, a published tunnel can request it directly. For example, an HTTP tunnel uses:

rstream forward 8080 --http --host api.example.com

The same hostname contract applies to published TLS, QUIC, and DTLS tunnels. The engine verifies that the authenticated project owns the hostname before adding the route and presents the managed certificate when it terminates the secure transport. A hostname can be used by only one active tunnel at a time on a standalone engine.

Deleting a custom hostname withdraws its route authorization. Reachable engines receive the change immediately, while private engines revalidate active routes under a bounded authorization lease.

Declarative configuration

Register and verify the hostname from the project dashboard before referring to it from a tunnel configuration. Registration establishes project ownership; YAML and Docker labels only select that registered hostname when the tunnel starts.

version: 1
tunnels:
  - name: api
    forward: 8080
    tunnel:
      publish: true
      protocol: http
      host: api.example.com

The equivalent Docker labels are:

labels:
  rstream.tunnel.api.forward: "8080"
  rstream.tunnel.api.publish: "true"
  rstream.tunnel.api.protocol: "http"
  rstream.tunnel.api.host: "api.example.com"

The host key maps to the tunnel hostname property. The engine rejects the configuration if the hostname is not registered to the authenticated project or is already used by another live tunnel.

TLS passthrough

Managed certificates apply when rstream terminates TLS. A TLS passthrough tunnel still requires a verified custom hostname, but not a ready managed certificate: the upstream service presents and renews its own certificate.

rstream forward 8443 --tls --tls-mode passthrough --host secure.example.com

rstream reserves the acme-tls/1 application protocol for certificates it manages and does not forward it through a passthrough tunnel. An upstream service behind passthrough must therefore use DNS-01 or another validation path that does not rely on TLS-ALPN-01 through rstream.