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>
      http:
        version: http/1.1
        upstreamTLS: false
        auth:
          token: true

The forward field accepts port and host:port 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

upstreamTLS enables TLS between the engine and the upstream service. For HTTP tunnels, tunnel.http.upstreamTLS is still accepted as an HTTP-scoped alias, but new configs should prefer the top-level upstreamTLS.

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.

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