Complete YAML Configuration Reference for olcRTC Tunnel

olcRTC reads all runtime settings from a single YAML file passed as the only CLI argument. There are no separate CLI flags for mode, transport, or provider — everything lives in YAML.

olcrtc /path/to/server.yaml
olcrtc /path/to/client.yaml

Complete YAML Schema

YAML Path	Description
`mode`	Role: `srv` (server), `cnc` (client), or `gen` (room generation)
`auth.provider`	Signaling provider: `jitsi`, `telemost`, `wbstream`, or `none`
`auth.token`	Pre-issued account token for `wbstream`; empty uses the guest flow
`room.id`	Room ID or URL for the chosen provider
`room.channel`	Optional channel ID for peer-routing scenarios
`crypto.key`	Shared secret: exactly 64 hex characters (32 bytes)
`crypto.key_file`	Path to a file containing the key; read relative to the YAML file
`net.transport`	Wire transport: `datachannel`, `vp8channel`, `seichannel`, or `videochannel`
`net.dns`	DNS resolver in `host:port` form, e.g. `8.8.8.8:53`
`socks.host`	Local SOCKS5 listener address (`cnc` only), default `127.0.0.1`
`socks.port`	Local SOCKS5 listener port (`cnc` only), default `1080`
`socks.user`	Login for incoming SOCKS5 connections (`cnc` only, optional)
`socks.pass`	Password for incoming SOCKS5 connections (`cnc` only, optional)
`socks.proxy_addr`	Address of outbound SOCKS5 proxy (`srv` only)
`socks.proxy_port`	Port of outbound SOCKS5 proxy (`srv` only)
`socks.proxy_user`	Login for upstream proxy authentication (RFC 1929, `srv` only)
`socks.proxy_pass`	Password for upstream proxy authentication (RFC 1929, `srv` only)
`engine.name`	Direct engine: `livekit`, `goolom`, or `jitsi` — only when `auth.provider: none`
`engine.url`	SFU endpoint URL for direct engine mode
`engine.token`	Auth token for direct engine mode
`video.codec`	`qrcode` or `tile` (`videochannel` only)
`video.width`	Frame width in pixels, default `1920`
`video.height`	Frame height in pixels, default `1080`
`video.fps`	Frames per second, default `30`
`video.bitrate`	Bitrate string, e.g. `"2M"` or `"5000k"`, default `"2M"`
`video.hw`	Hardware acceleration: `none` or `nvenc`, default `none`
`video.qr_recovery`	QR error correction: `low`, `medium`, `high`, or `highest`, default `low`
`video.qr_size`	QR fragment size in bytes; `0` = auto
`video.tile_module`	Tile size in pixels 1–270 (`tile` codec only), default `4`
`video.tile_rs`	Reed-Solomon parity percentage 0–200 (`tile` codec only), default `20`
`vp8.fps`	VP8 stream FPS (`vp8channel` only), default `30`
`vp8.batch_size`	Frames per tick (`vp8channel` only), default `64`
`sei.fps`	H.264 stream FPS (`seichannel` only), default `30`
`sei.batch_size`	Frames per tick (`seichannel` only), default `64`
`sei.fragment_size`	Fragment size in bytes (`seichannel` only), default `900`
`sei.ack_timeout_ms`	ACK timeout in milliseconds (`seichannel` only), default `2000`
`liveness.interval`	Ping interval over the control stream, default `10s`
`liveness.timeout`	How long to wait for a pong, default `5s`
`liveness.failures`	Consecutive missed pongs before session rebuild, default `3`
`lifecycle.max_session_duration`	Planned session rebuild duration, e.g. `6h`; empty = disabled
`traffic.max_payload_size`	Encrypted wire-message size limit; `0` = transport limit
`traffic.min_delay`	Minimum send pacing delay, e.g. `5ms`
`traffic.max_delay`	Maximum send pacing delay, e.g. `30ms`
`gen.amount`	Number of rooms to create in `gen` mode
`profiles[]`	Ordered list of failover profiles for `srv`/`cnc`
`failover.retry_delay`	Pause before switching to the next profile, e.g. `2s`
`failover.max_cycles`	Full passes over the profile list; `0` = infinite
`data`	Path to the directory with runtime data (`names`, `surnames`); use `data`
`debug`	Enables verbose logging when `true`
`ffmpeg`	Path to the `ffmpeg` binary for `videochannel`; default `ffmpeg`

Minimal Examples

Server (Jitsi + datachannel)

# server.yaml — jitsi + datachannel
mode: srv

auth:
  provider: jitsi

room:
  # Full URL: https://HOST/ROOM
  # Pick a reachable host from docs/examples/jitsi.instances.yaml
  id: "https://meet.example.org/REPLACE_WITH_ROOM_NAME"

crypto:
  # Generate: openssl rand -hex 32
  key: "REPLACE_ME_WITH_64_HEX_CHARS"

net:
  transport: datachannel
  dns: "8.8.8.8:53"

data: data

Client (Jitsi + datachannel)

# client.yaml — jitsi + datachannel
mode: cnc

auth:
  provider: jitsi

room:
  # Must match the server exactly
  id: "https://meet.example.org/REPLACE_WITH_ROOM_NAME"

crypto:
  key: "REPLACE_ME_WITH_64_HEX_CHARS"

net:
  transport: datachannel
  dns: "8.8.8.8:53"

socks:
  host: "127.0.0.1"
  port: 8808

data: data

Crypto Key Configuration

crypto.key_file is read relative to the YAML file’s directory, not the working directory. You cannot set crypto.key and crypto.key_file at the same time — the loader returns ErrCryptoKeyConflict if both are present.

Store your key in a separate file to avoid embedding secrets in your config:

crypto:
  key_file: "./olcrtc.key"

Generate a key:

openssl rand -hex 32 > olcrtc.key

Liveness

After CLIENT_HELLO / SERVER_WELCOME, the first smux stream stays open as an encrypted control stream. olcRTC sends CONTROL_PING / CONTROL_PONG over this stream to verify the actually working tunnel path, not just the WebRTC connection status.

liveness:
  interval: 10s   # how often to send pings
  timeout: 5s     # how long to wait for a pong
  failures: 3     # consecutive missed pongs before rebuild

When failures consecutive pongs are missed, the current smux session is torn down and rebuilt. In failover mode the failed profile hands control to the supervisor, which moves to the next profile in the list.

Lifecycle Rotation

lifecycle.max_session_duration sets a planned upper bound on a single provider session. When the timer expires, the active srv or cnc session is closed and restarted with the same config.

lifecycle:
  max_session_duration: 6h

The field is optional. When enabled, a clean session end is also restarted so the other peer can catch up with the planned rebuild. Accepted format is Go duration: 30m, 2h, 6h. Zero and negative values are not accepted.

Traffic Shaping

traffic adds a common wrapper around the chosen transport to limit wire-message size and add a small pacing delay before sending. Data is not truncated: if a payload does not fit the effective limit, the send returns an explicit error.

traffic:
  max_payload_size: 4096   # 0 = transport limit
  min_delay: 5ms
  max_delay: 30ms

max_payload_size is clamped to the MaxPayloadSize declared by the chosen transport. The smux frame size is also reduced by the crypto overhead.
If only min_delay is set, the delay is fixed at that value.
Use the same traffic settings on both server and client.

Server-only Fields (`mode: srv`)

These fields control the outbound SOCKS5 proxy used by the server for egress traffic:

Field	Description
`socks.proxy_addr`	Address of the upstream SOCKS5 proxy, e.g. `"127.0.0.1"`
`socks.proxy_port`	Port of the upstream proxy, e.g. `1080`
`socks.proxy_user`	Login for upstream proxy auth (RFC 1929); empty = no auth
`socks.proxy_pass`	Password for upstream proxy auth; optional even when user is set

If socks.proxy_user is empty the server reaches the proxy without authentication (method 0x00). If it is set, username/password auth per RFC 1929 is used.

Client-only Fields (`mode: cnc`)

These fields control the local SOCKS5 listener that applications connect to:

Field	Description	Default
`socks.host`	Address to listen on	`127.0.0.1`
`socks.port`	Port to listen on	`1080`
`socks.user`	Login for incoming SOCKS5 connections (optional)	—
`socks.pass`	Password for incoming SOCKS5 connections (optional)	—

If socks.host is not a loopback address (127.0.0.1, ::1, or localhost), both socks.user and socks.pass must be set. This prevents accidentally exposing an open SOCKS5 proxy on the local network or the internet.

If socks.user is not set, authentication is disabled and any local client may connect. If it is set, only connections presenting the correct credentials (RFC 1929) are accepted.

Transport Reference

datachannel
vp8channel
seichannel
videochannel

datachannel carries data over the WebRTC SCTP data channel. It requires no extra fields and is the simplest transport.

datachannel with Jitsi is the recommended starting point: stable, no registration required, works on any public or self-hosted Jitsi Meet instance.

net:
  transport: datachannel
  dns: "8.8.8.8:53"

No additional datachannel-specific fields exist.

vp8channel tunnels data inside VP8 video frames. It is stable on Jitsi and WbStream.

Recommended settings: fps: 30, batch_size: 64. Lower FPS reduces CPU load; a larger batch size increases throughput.

Field	Description	Default
`vp8.fps`	VP8 stream FPS	`30`
`vp8.batch_size`	Frames per tick	`64`

net:
  transport: vp8channel
  dns: "8.8.8.8:53"

vp8:
  fps: 30
  batch_size: 64

seichannel embeds data in SEI NAL units inside an H.264 video stream.

Recommended settings: fps: 30, batch_size: 64, fragment_size: 900, ack_timeout_ms: 2000.

Field	Description	Default
`sei.fps`	H.264 stream FPS	`30`
`sei.batch_size`	Frames per tick	`64`
`sei.fragment_size`	Fragment size in bytes	`900`
`sei.ack_timeout_ms`	ACK timeout in milliseconds	`2000`

net:
  transport: seichannel
  dns: "8.8.8.8:53"

sei:
  fps: 30
  batch_size: 64
  fragment_size: 900
  ack_timeout_ms: 2000

videochannel encodes data into video frames rendered and decoded via ffmpeg. It is the most compatible but slowest transport.

Recommended settings: codec: qrcode, width: 1080, height: 1080, fps: 30, bitrate: "5000k", hw: none. The tile codec requires exactly 1080×1080.

Field	Description	Default
`video.codec`	`qrcode` or `tile`	`qrcode`
`video.width`	Frame width in pixels	`1920`
`video.height`	Frame height in pixels	`1080`
`video.fps`	Frames per second	`30`
`video.bitrate`	Bitrate string, e.g. `"2M"` or `"5000k"`	`"2M"`
`video.hw`	Hardware acceleration: `none` or `nvenc`	`none`
`video.qr_recovery`	QR error correction: `low` / `medium` / `high` / `highest`	`low`
`video.qr_size`	QR fragment size in bytes; `0` = auto	`0`
`video.tile_module`	Tile pixel size 1–270 (`tile` only)	`4`
`video.tile_rs`	Reed-Solomon parity % 0–200 (`tile` only)	`20`
`ffmpeg`	Path to the `ffmpeg` binary	`ffmpeg`

net:
  transport: videochannel
  dns: "8.8.8.8:53"

video:
  codec: qrcode
  width: 1080
  height: 1080
  fps: 30
  bitrate: "5000k"
  hw: none
  qr_recovery: low
  qr_size: 0

ffmpeg: ffmpeg

The tile codec requires exactly 1080×1080 pixels. The ffmpeg binary must be on PATH or specified via the top-level ffmpeg field.

mode: gen

gen mode is reserved for auth providers that implement room creation via an API. The current built-in providers (jitsi, telemost, wbstream) do not create rooms through olcRTC:

Telemost / WbStream — create the room on the service website and paste the room ID into room.id.
Jitsi — specify any room URL; Jitsi creates rooms on first join.

mode: gen

auth:
  provider: jitsi

gen:
  amount: 5

data: data

Get Started

Configuration

Reference

Integrations

Complete YAML Configuration Reference for olcRTC Tunnel

Complete YAML Schema

Minimal Examples

Server (Jitsi + datachannel)

Client (Jitsi + datachannel)

Crypto Key Configuration

Liveness

Lifecycle Rotation

Traffic Shaping

Server-only Fields (`mode: srv`)

Client-only Fields (`mode: cnc`)

Transport Reference

mode: gen

Build docs developers (and LLMs) love

Get Started

Configuration

Reference

Integrations

Documentation Index

​Complete YAML Schema

​Minimal Examples

​Server (Jitsi + datachannel)

​Client (Jitsi + datachannel)

​Crypto Key Configuration

​Liveness

​Lifecycle Rotation

​Traffic Shaping

​Server-only Fields (mode: srv)

​Client-only Fields (mode: cnc)

​Transport Reference

​mode: gen

Build docs developers (and LLMs) love

Complete YAML Schema

Minimal Examples

Server (Jitsi + datachannel)

Client (Jitsi + datachannel)

Crypto Key Configuration

Liveness

Lifecycle Rotation

Traffic Shaping

Server-only Fields (`mode: srv`)

Client-only Fields (`mode: cnc`)

Transport Reference

mode: gen