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 domain

A registered hostname covers one DNS name, such as api.example.com. A registered wildcard covers its immediate subdomains, such as *.example.com. Add the domain from the project dashboard or CLI, then publish the DNS records returned for it. The records are generated from the selected cluster and should be copied exactly.

The CLI uses the project selected by the current context. Register an individual hostname with TLS-ALPN-01:

rstream project domain add api.example.com \
  --kind hostname \
  --certificate-validation tls-alpn-01 \
  -o yaml

Use DNS-01 when the engine does not receive public TLS traffic on port 443:

rstream project domain add api.example.com \
  --kind hostname \
  --certificate-validation dns-01 \
  -o yaml

A wildcard always uses DNS-01. Pass its base domain to the CLI:

rstream project domain add example.com \
  --kind wildcard \
  --certificate-validation dns-01 \
  -o yaml

Structured output includes the ownership, traffic, certificate-validation, and certificate-state records. After publishing them, ask the Control plane to verify the domain:

rstream project domain verify api.example.com -o yaml

List registered hostnames or remove one by name:

rstream project domain list -o yaml
rstream project domain remove api.example.com

Pass --project-id <project-id> to any of these commands when the current context should not select the project.

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.

TLS-ALPN-01 validates an individual hostname through public TCP port 443 after its traffic record points to the engine. It requires no additional ACME DNS record.

DNS-01 delegates certificate validation through the additional CNAME record returned by rstream. It supports both individual hostnames and wildcards and does not require the engine to receive public traffic on port 443. The available validation methods depend on the selected deployment.

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 a 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

For a wildcard registration, select one concrete hostname covered by it:

rstream forward 8080 --http --host app.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 or CLI 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.