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>"
    engine: "<engine>"
    auth:
      token:
        storage:
          kind: inline
          value: "<token>"
    transport:
      mptcp: false

The example shows inline token storage. Advanced configurations can store tokens in macOS Keychain or use PKCS#11-backed mTLS private keys. Those shapes are documented in Credential Storage.

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 token authentication. 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.

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 still require token authentication. 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:
  useQuic: true
  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.