examples/

README

Examples

The examples use the same config/env resolution as the CLI via config.NewClientFromEnv(). That keeps the sample code short and consistent with rstream usage.

Prerequisites

Set a default context or RSTREAM_ENGINE. If your engine requires token authentication, set RSTREAM_AUTHENTICATION_TOKEN. If the example opens an agent control-channel connection and it requires mTLS agent authentication, set RSTREAM_MTLS_CERT_FILE and RSTREAM_MTLS_KEY_FILE instead. Examples that call the Engine HTTP API require token authentication.

Typical setup (CLI):

rstream login <token>
rstream project use <project-endpoint>

Run

Build all examples:

make examples

Run an example:

./out/examples/http-h1-server --publish

Useful protocol-focused examples:

• tcp-ssh-server / tcp-ssh-client: SSH over a published raw TCP tunnel, with password authentication and explicit host key verification.
• http-sse-server / http-sse-client: Server-Sent Events over an HTTP tunnel.
• sctp-echo-server / sctp-echo-client: SCTP streams with pion/sctp over datagram tunnels, and over the published DTLS edge.
• masque-server / masque-client: CONNECT-UDP and CONNECT-IP over HTTP/3 datagram tunnels, using internal rstream dialing by default and published HTTP/3 endpoints with --publish.

Run the MASQUE examples in private mode:

go run ./examples/masque-server --variant connect-udp
go run ./examples/masque-client --variant connect-udp --target 127.0.0.1:9000

Run the same shape through a published HTTP/3 endpoint:

go run ./examples/masque-server --variant connect-udp --publish
go run ./examples/masque-client --variant connect-udp --publish --target 127.0.0.1:9000

Run the SSH server through an ephemeral published TCP address:

RSTREAM_SSH_PASSWORD='<password>' go run ./examples/tcp-ssh-server

Use the address and host key fingerprint printed by the server:

RSTREAM_SSH_PASSWORD='<password>' go run ./examples/tcp-ssh-client \
  -address '<hostname>:<port>' \
  -fingerprint 'SHA256:<fingerprint>'

The downstream TCP connection is not secured by rstream. SSH provides encryption, server identity, and client authentication in this example.

Generate managed TURN credentials from the active config context:

go run ./examples/turn-credentials

Or override the current context with environment variables:

RSTREAM_API_URL=http://localhost:3000 \
RSTREAM_AUTHENTICATION_TOKEN="$RSTREAM_AUTHENTICATION_TOKEN" \
RSTREAM_PROJECT_ENDPOINT=9bfdaa8b \
go run ./examples/turn-credentials

When TURN routing fields are not already present in the local context, the SDK falls back to the Control plane API.

CLI Run Examples

• examples/run-yaml: YAML-based rstream -v run --apply example with a whoami container.
• examples/run-docker: Docker-label-based rstream -v run --docker example with a whoami container.