Configuration File

The rstream CLI stores its local state in a YAML configuration file. The file contains defaults, environments, and named contexts. Commands such as rstream login, rstream project use, and rstream context create update this file.

The configuration schema is intentionally small. Most application and agent workflows rely on a default context. Contexts define the Engine endpoint and the authentication method used by the agent or SDK process.

File structure

At the top level, the configuration contains version, defaults, environments, and contexts. A minimal context-based runtime configuration looks like this:

version: 1
defaults:
  context:
    name: dev
contexts:
  - name: dev
    projectEndpoint: "<project-endpoint>"
    region: "eu-west-3"
    engine: "<engine>"
    auth:
      token:
        storage:
          kind: inline
          value: "<token>"
    transport:
      mptcp: false

The example shows inline token storage. region is optional and applies only to contexts linked to a managed project. It selects one of the regions exposed by that project and cannot be combined with a runtime engine override. Resolving a region selector needs Control plane metadata; certificate-only devices should use an explicit regional engine address without a selector. Advanced configurations can store tokens in macOS Keychain or use PKCS#11-backed mTLS private keys or an external signer (storage.kind: exec). Those shapes are documented in Credential Storage.

Control plane access gateway

An environment can attach custom headers to requests sent to its Control plane API. This is useful when the API is protected by an additional deployment access gateway:

environments:
  - apiUrl: "https://control.example.com"
    headers:
      X-Deployment-Access: "<value>"
contexts:
  - name: private-control-plane
    apiUrl: "https://control.example.com"
    projectEndpoint: "<project-endpoint>"

These headers are separate from rstream authentication. Authorization, cookie, forwarding, host, and hop-by-hop headers are reserved. Invalid values and case-insensitive duplicates are rejected before network I/O, and the configured headers are not forwarded if the Control plane returns a redirect.

Authentication

Each context can authenticate the agent control-channel connection with either a token or an mTLS client certificate. This is the authentication used by rstream forward, rstream run, SDK runtimes, private dialing, tunnel creation, and stream attachment.

Agent authentication is separate from Engine HTTP API authentication and published Tunnel access. Engine HTTP API endpoints such as tunnel listing, SSE, and WebSocket watch streams use the selected token or certificate identity. The SDK discovers a dedicated mTLS authority when a certificate is selected. A public tunnel URL can require token authentication, rstream Auth, or mTLS for incoming clients, but that policy is configured on the tunnel and does not replace the agent's control-channel authentication.

Token auth and mTLS auth are mutually exclusive for one agent control-channel connection. If both are configured for the same connection, the CLI fails before opening the control channel.

Token authentication stores a token reference under auth.token:

contexts:
  - name: prod-token
    engine: "<engine>"
    auth:
      token:
        storage:
          kind: inline
          value: "<project-scoped-token>"

This shape is the usual fit for CI runners, backend services, and devices that use scoped tokens.

mTLS authentication stores a client certificate and private key under auth.mtls. File paths are the normal production shape:

contexts:
  - name: prod-mtls
    engine: "<engine>"
    auth:
      mtls:
        certificateFile: /etc/rstream/client.pem
        keyFile: /etc/rstream/client-key.pem

The certificate must also be registered as an mTLS Client Certificate (MTLS) credential in the dashboard. rstream stores the certificate fingerprint and uses the credential's Engine API permissions and resources.tunnels boundaries when the certificate authenticates on supported mTLS surfaces.

Inline certificate material is also supported for generated or ephemeral configs:

contexts:
  - name: ephemeral-mtls
    engine: "<engine>"
    auth:
      mtls:
        certificate: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----
        key: |
          -----BEGIN PRIVATE KEY-----
          ...
          -----END PRIVATE KEY-----

Certificate and key values must be complete pairs. Do not mix inline certificate material with file-based keys in the same auth.mtls block. Do not mix these aliases with auth.mtls.storage; hardened storage backends have their own nested fields.

The standard Go SDK and CLI also support an external signer under auth.mtls.storage.kind: exec, with a required certificateSHA256 pin and nested exec.command, args, timeout, maxConcurrency, and passEnv settings. See Credential Storage for the complete schema and CLI creation flags. Other SDKs reject this mode when selected.

In the Go configuration bridge, context authentication takes precedence as a complete identity over environment authentication. A context using mTLS can coexist with an environment's administrative token. Explicit token and mTLS credentials for the same runtime connection still conflict. Control plane requests continue to resolve token credentials separately.

rstream run --apply references the shared context through an external: true context entry. Docker mode uses the selected shared context, or explicitly enabled context labels. Neither Docker labels nor a WebTTY settings file can define an executable signer. See the Go run configuration guide.

For stateless agents, the equivalent environment variables are RSTREAM_MTLS_CERT_FILE and RSTREAM_MTLS_KEY_FILE:

RSTREAM_ENGINE="<engine-host:port>" \
RSTREAM_MTLS_CERT_FILE="/etc/rstream/client.pem" \
RSTREAM_MTLS_KEY_FILE="/etc/rstream/client-key.pem" \
rstream forward 8080

When both mTLS environment variables are set, the CLI uses mTLS for the agent control-channel connection and does not use a token from the selected context for that connection. Setting those variables together with RSTREAM_AUTHENTICATION_TOKEN is an error. Engine HTTP API requests reuse that certificate on the discovered dedicated authority. See mTLS for the surface and plan policy, and Environment Variables for precedence.

The transport block carries network-path settings for the client-to-edge session. A fuller example can select QUIC transport and an explicit DNS policy:

transport:
  mode: quic
  bind:
    mode: interface
    interface: en0
  proxy:
    fromEnvironment: true
    tls:
      caFile: /etc/rstream/proxy-ca.pem
      serverName: proxy.corp
      insecureSkipVerify: false
  dns:
    override: "1.1.1.1:853"
    tls: true
    serverName: "cloudflare-dns.com"
    dnssec: true

The proxy TLS block uses the usual TLS client controls. caFile adds a PEM trust bundle for the proxy certificate, serverName overrides the proxy SNI and certificate verification name, and insecureSkipVerify disables proxy certificate verification for controlled diagnostics. For transport semantics and the supported DNS, proxy, and QUIC options, see Tunnel Transports.