Configuration

The engine configuration is YAML with environment overrides. This page documents the public CE surface because this product documentation is the public contract for self-hosted CE operators.

Environment overrides use the RSTREAM_ENGINE_ prefix. Double underscores represent nested separators. For example, RSTREAM_ENGINE_ENGINE__HOST maps to engine.host, and RSTREAM_ENGINE_TLS__LISTEN_ADDR maps to tls.listen_addr.

Use double underscores for nested keys in operational configuration. Single underscores remain part of field names such as log_level, listen_addr, cert_file, and token_jwt_secret.

Community Edition Schema

The CE top-level sections are engine, http, tls, certs, auth, metrics, and timeouts.

engine:
  host: edge.example.com
  log_level: info
http:
  enabled: true
  listen_addr: "[::]:80"
tls:
  enabled: true
  listen_addr: "[::]:443"
certs:
  static:
    enabled: true
    cert_file: /etc/rstream/tls/cert.pem
    key_file: /etc/rstream/tls/key.pem
auth:
  jwt:
    enabled: true
    token_jwt_secret: "<read-from-env-in-production>"
metrics:
  prometheus:
    enabled: true
    listen_addr: "127.0.0.1:9090"
    path: /metrics
timeouts:
  stream_request_seconds: 30
  http_idle_seconds: 90

Required Fields

Field Reference

JWT Authentication

CE validates HS256 JWTs with auth.jwt.token_jwt_secret. A valid token authenticates to the engine host itself; there is no project endpoint in CE.

Use a high-entropy secret, bounded token lifetimes with exp, and a normal secret rotation process. CE does not persist token records and does not call the hosted Control plane.

export RSTREAM_ENGINE_JWT_SECRET="$(openssl rand -base64 32)"
export RSTREAM_AGENT_TOKEN="$(
  node <<'NODE'
const crypto = require("crypto");
const now = Math.floor(Date.now() / 1000);
const secret = process.env.RSTREAM_ENGINE_JWT_SECRET;
const b64 = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");
const header = b64({ alg: "HS256", typ: "JWT" });
const payload = b64({ type: "pat", sub: "agent", iat: now, exp: now + 3600 });
const signature = crypto.createHmac("sha256", secret).update(`${header}.${payload}`).digest("base64url");
console.log(`${header}.${payload}.${signature}`);
NODE
)"

Static TLS Provider

certs.static.cert_file and certs.static.key_file must point to files readable by the engine process. For CE, the certificate should include SANs for the base engine host and the tunnel wildcard:

DNS:edge.example.com
DNS:*.t.edge.example.com

The static provider reloads the certificate pair on a later TLS handshake when either file modification time changes. This allows an ACME sidecar to update the files without restarting the engine. Write renewed material to temporary files first, then rename both files into place so the engine never observes partially written PEM data.

Prometheus Metrics

Prometheus metrics are optional. When enabled, metrics.prometheus.listen_addr is required. The default path is /metrics when path is empty.

If the metrics listener binds to a non-loopback address, configure metrics.prometheus.bearer_token and make the scraper send:

Authorization: Bearer <metrics-token>

This guard prevents accidental exposure when the listener is bound to 0.0.0.0 or [::] for container networking.

Configuration Contract

The public CE configuration contract is the schema documented on this page. Keep CE configuration limited to those fields. If configuration validation rejects an extra section, remove it and use the documented CE fields.

Use hosted rstream or contact rstream for a private deployment when the runtime must enforce managed project controls, certificate-backed authentication, browser-based access flows, network access policies, persisted operational history, or automatic certificate management.