YAML

In apply mode, rstream run reads a YAML file that describes tunnels and optional contexts. The loader expands environment variables before decoding and rejects unknown fields, which makes the configuration suitable for version control and infrastructure-as-code workflows.

The root schema contains version, tunnels, and an optional contexts map. The current supported version is 1.

Minimal example

version: 1
tunnels:
  - name: dev-api
    forward: 8080
    tunnel:
      publish: true
      protocol: http
      host: api-<project-endpoint>.t.<engine-host>
      upstreamTLS: false
      http:
        version: http/1.1
        auth:
          token: true

The forward field accepts port, host:port, and bracketed IPv6 ([2001:db8::1]:8080) forms and defaults the host to localhost when only a port is provided.

The host field requests a stable domain for a published tunnel. It maps to the engine hostname property and must belong to the current project namespace.

TLS options

Non-HTTP published tunnels can configure upstream TLS and ALPN values from the same file.

version: 1
tunnels:
  - name: stream
    forward: 9443
    tunnel:
      publish: true
      protocol: tls
      upstreamTLS: true
      tls:
        alpns:
          - rstream-stream-echo

tunnel.upstreamTLS enables TLS between the engine and the upstream service. It corresponds to CLI --upstream-tls and Docker label upstream-tls.

tunnel.tls.ciphers is a list equivalent to rstream forward --tls-ciphers:

tls:
  mode: terminated
  minVersion: tls1.3
  ciphers:
    - TLS_AES_128_GCM_SHA256

An explicit false is preserved across CLI, YAML and Docker labels.

Published TCP

Set protocol: tcp to publish a raw TCP service. Omit port for an ephemeral address, or set it to a TCP port already reserved by the project:

version: 1
tunnels:
  - name: ssh
    forward: 22
    tunnel:
      publish: true
      protocol: tcp
      port: 10042

TCP tunnels are always published bytestream tunnels. They do not accept host, HTTP, TLS, or edge authentication options. See TCP Tunnels before exposing a service: rstream does not secure the downstream TCP connection.

Context selection

A tunnel can reference a context in three ways: an inline context object, a named context entry from the file, or the fallback context provided by the CLI runtime. A fallback context must include an engine and token or mTLS identity.

Named contexts can also be marked as external. In that case, the name is resolved through the CLI context store.

Use inline contexts when the file is generated for one deployment, named contexts when several tunnels in the same file share one target project, and external contexts when the environment already manages the CLI context store. Secret values can come from environment expansion so the YAML can remain versioned without storing tokens.

Validation behavior

The decoder runs in strict mode and rejects unknown keys, including nested transport fields inside inline contexts, and additional YAML documents. Each apply file must contain exactly one document. Explicit empty enum values and hostnames are errors; omit those fields to leave them unspecified. Duplicate tunnel names are rejected. Missing required fields (name, forward, and tunnel) fail the load.

Validation happens before reconciliation. CI can run the same command against a candidate file and fail early on unknown fields, duplicate tunnel names, unsupported protocol combinations, or missing required fields. In long-running apply mode, an invalid update is reported and the previous valid runtime state remains the last known good target.

CLI flags, YAML tunnel fields and Docker labels share tunnel normalization and validation rules. Docker keeps its publish=true and protocol=http defaults; forward and apply leave unspecified exposure settings to the tunnel API. Interactive output and reconnect flags belong to the command, while run reconciles the declared tunnels. The shared SDK account/context file is separate from this apply schema.