Build olcRTC Natively from Source with Go 1.26+ and Mage

For those who prefer a native binary without Podman or containers, olcRTC can be built directly on the host using the standard Go toolchain and mage. This approach gives you full control over the binary, makes it easy to integrate with systemd, and lets you cross-compile for other platforms. You need Go 1.26+, mage, and git.

olcRTC is in Beta. Always verify that the video call service you choose is accessible in your network before relying on it.

SWAP Recommendation

If your machine has less than 4 GB of RAM, the build may crash. Enable a swap file first:

sudo fallocate -l 4G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile

Build and Run

Install git

apt install git

Install Go 1.26+

pacman -S go

On Debian/Ubuntu, the system package is typically Go 1.19 — too old. Use APT pinning or the Go SDK path instead:

APT Pinning (Debian 13+)
Go SDK Path (any Ubuntu/Debian)

This is the recommended approach on Debian 13+. It pulls Go from the testing repository without polluting the rest of the system.

echo 'deb http://deb.debian.org/debian/ testing main non-free-firmware' | sudo tee /etc/apt/sources.list.d/testing.list

cat <<EOF | sudo tee /etc/apt/preferences.d/testing-pin
Package: *
Pin: release a=testing
Pin-Priority: 100
EOF

sudo apt update
sudo apt install -t testing golang-go

sudo update-alternatives --install /usr/bin/go go `which go` 10
sudo update-alternatives --install /usr/bin/gofmt gofmt `which gofmt` 10

Use the old system Go only to bootstrap the download of Go 1.26:

apt install golang                          # install old go (bootstrap only)
go install golang.org/dl/go1.26.0@latest    # download the go1.26 installer
~/go/bin/go1.26.0 download                  # download go1.26 itself
mv ~/go/bin/go1.26.0 /usr/local/bin/go      # replace the system go

Verify the installation:

go version
# go version go1.26.x linux/amd64

Install mage

mage is the build system used by olcRTC — similar to make but written in Go.

go install github.com/magefile/mage@latest

Add ~/go/bin to your PATH so the shell can find mage:

echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Verify:

mage --version
# mage vx.x.x

Clone the repository

git clone https://github.com/openlibrecommunity/olcrtc
cd olcrtc

Build the binary

Build for the current platform:

mage build

Cross-compile for all supported platforms at once (Linux amd64/arm64, Windows amd64, macOS amd64/arm64, FreeBSD amd64/arm64, OpenBSD amd64/arm64):

mage cross

The resulting binary is placed in build/:

build/olcrtc-linux-amd64

Generate the encryption key

Generate a 64-character hex key. This is done once on the server; the same key must be used on both server and client.

openssl rand -hex 32
# d823fa01cb3e0609b67322f7cf984c4ee2e4ce2e294936fc24ef38c9e59f4799

Save this output — you will need it for both config files.

Run the server

On the server machine (VPS, remote server, etc.). Create a YAML config file, then run the binary with it.

Recommended: jitsi + datachannel. No registration, stable data path, lowest latency. See docs/examples/jitsi.instances.yaml for a list of public Jitsi instances — verify in your browser that the instance you choose actually loads before using it.

jitsi + datachannel (recommended)
wbstream + vp8channel (alternative)

# server.yaml
mode: srv
auth:
  provider: jitsi
room:
  # Instances: see docs/examples/jitsi.instances.yaml
  id: "https://meet.example.org/myroom"
crypto:
  key: "d823fa01cb3e0609b67322f7cf984c4ee2e4ce2e294936fc24ef38c9e59f4799"
net:
  transport: datachannel
  dns: "8.8.8.8:53"
data: data

./build/olcrtc-linux-amd64 server.yaml

The server joins the room as a participant (without camera or microphone) and waits for the client. Note that Jicofo does not issue a session-initiate until a second participant joins — this is a Jitsi quirk, not an olcRTC issue.

Create a room through the WbStream site and paste its ID into room.id.

wbstream + datachannel does not work in the normal guest flow. WbStream issues guest tokens with canPublishData=false, so the data channel does not carry data. Use vp8channel, seichannel, or videochannel with WbStream.

# server.yaml
mode: srv
auth:
  provider: wbstream
room:
  id: "<room-id-from-stream.wb.ru>"
crypto:
  key: "d823fa01cb3e0609b67322f7cf984c4ee2e4ce2e294936fc24ef38c9e59f4799"
net:
  transport: vp8channel
  dns: "8.8.8.8:53"
data: data

./build/olcrtc-linux-amd64 server.yaml

To see every connection in the logs, add debug: true to your YAML:

debug: true

Example debug output:

2026/05/03 08:05:23 Connecting link via direct/vp8channel/wbstream...
2026/05/03 08:05:25 wbstream publisher state: connected
2026/05/03 08:05:27 Link connected
2026/05/03 08:05:43 sid=3 connect icanhazip.com:443
2026/05/03 08:05:43 sid=3 connected icanhazip.com

Run the client

On your local machine. auth.provider, net.transport, room.id, and crypto.key must match the server exactly.

jitsi + datachannel (recommended)
wbstream + vp8channel (alternative)
With SOCKS5 auth

# client.yaml
mode: cnc
auth:
  provider: jitsi
room:
  # Instances: see docs/examples/jitsi.instances.yaml
  id: "https://meet.example.org/myroom"
crypto:
  key: "<hex-key-same-as-on-the-server>"
net:
  transport: datachannel
  dns: "8.8.8.8:53"
socks:
  host: "127.0.0.1"
  port: 8808
data: data

./build/olcrtc-linux-amd64 client.yaml

After startup, SOCKS5 listens on 127.0.0.1:8808.

# client.yaml
mode: cnc
auth:
  provider: wbstream
room:
  id: "<room-id>"
crypto:
  key: "<hex-key>"
net:
  transport: vp8channel
  dns: "8.8.8.8:53"
socks:
  host: "127.0.0.1"
  port: 8808
data: data

./build/olcrtc-linux-amd64 client.yaml

The logs will confirm:

SOCKS5 server listening on 127.0.0.1:8808

To protect the proxy with a username and password (e.g. on a shared machine), add socks.user and socks.pass:

# client.yaml
mode: cnc
auth:
  provider: jitsi
room:
  id: "https://meet.example.org/myroom"
crypto:
  key: "<hex-key>"
net:
  transport: datachannel
  dns: "8.8.8.8:53"
socks:
  host: "127.0.0.1"
  port: 8808
  user: myuser
  pass: mypass
data: data

For Android, owenewans/owenclave reads the olcrtc:// URI directly — no YAML or binary needed on the device.

Verify the tunnel

Send a request through the SOCKS5 proxy. The response should show your server’s IP:

curl --socks5-hostname 127.0.0.1:8808 https://icanhazip.com

All Mage Targets

Build

Target	What it does
`mage build`	Build the `olcrtc` binary for the current platform → `build/olcrtc-<os>-<arch>`
`mage cross`	Cross-compile for all supported platforms (Linux, Windows, macOS, FreeBSD, OpenBSD; amd64 + arm64)
`mage mobile`	Build the Android AAR via gomobile → `build/olcrtc.aar`
`mage clean`	Remove the `build/` directory

mage build    # native binary for this machine
mage cross    # all platforms
mage mobile   # Android AAR (requires gomobile)
mage clean    # wipe build/

Code Quality

Target	What it does
`mage vet`	Run `go vet` on the whole module
`mage lint`	Run `golangci-lint ./...`
`mage tidy`	Run `go mod tidy` and `go mod verify`
`mage deps`	Run `go mod download`

mage vet
mage lint
mage tidy
mage deps

Tests

Target	What it does
`mage test`	Unit tests in `-short` mode — fast, no network
`mage testFull`	All unit tests + local e2e with `-race`; no real providers
`mage e2e`	Smoke matrix against real providers
`mage stress`	Stress matrix against real providers (~6 hours)
`mage soak`	Real-provider throughput soak (long)
`mage localSoak`	In-memory throughput soak — no network required

mage test       # quick units
mage testFull   # full units + fast e2e, race detector
mage e2e        # real-provider smoke
mage stress     # real-provider stress (~6h)
mage soak       # real-provider soak
mage localSoak  # local in-memory soak

Pipelines

Target	What it does
`mage check`	`build + vet + lint + testFull` — run before every commit
`mage all`	`check + e2e` — full pre-merge pipeline
`mage nightly`	`all + stress` — nightly CI (~6 hours)
`mage everything`	`nightly + soak + localSoak` — full validation (12+ hours)

mage check       # pre-commit
mage all         # pre-merge
mage nightly     # nightly CI (~6h)
mage everything  # maximum confidence (12+ h)

Help

mage help (or mage -l) lists all available targets. Running mage with no arguments also prints the target list — Help is the default target.

mage help   # list all targets
mage -l     # same as mage help
mage        # no arguments — also prints target list

E2E Environment Variables

Fine-tune test runs through environment variables:

Variable	Applies to	Default	Description
`E2E_CARRIERS`	`e2e`, `stress`	all	Comma-separated list of carriers to test (e.g. `jitsi,wbstream`)
`E2E_TRANSPORTS`	`e2e`, `stress`	all	Comma-separated list of transports to test
`E2E_TIMEOUT`	`e2e`	`30m`	Per-test timeout
`E2E_STRESS`	`e2e`	—	Set to any value to enable stress mode inside `e2e`
`E2E_STRESS_DURATION`	`e2e`	—	Stress duration when `E2E_STRESS` is set
`STRESS_BULK_DURATION`	`stress`	`15m`	Duration of the bulk-transfer phase per case
`STRESS_ECHO_DURATION`	`stress`	`15m`	Duration of the echo phase per case
`STRESS_CASE_TIMEOUT`	`stress`	`35m`	Hard timeout per stress case
`STRESS_TIMEOUT`	`stress`	`6h`	Hard timeout for the entire stress run
`SOAK_CARRIERS`	`soak`	`telemost,jitsi,wbstream`	Carriers to soak
`SOAK_TRANSPORTS`	`soak`	`datachannel,vp8channel`	Transports to soak (real provider soak)
`SOAK_TRANSPORTS`	`localSoak`	`all`	Transports to soak (local in-memory soak)
`SOAK_DURATION`	`soak`, `localSoak`	`10m` (`6m` local)	How long to soak
`SOAK_CHAOS`	`localSoak`	—	Enable chaos mode in the local soak

Example — run a single targeted stress case:

E2E_CARRIERS=telemost E2E_TRANSPORTS=videochannel \
    STRESS_BULK_DURATION=0 STRESS_ECHO_DURATION=0 \
    STRESS_CASE_TIMEOUT=2m STRESS_TIMEOUT=3m mage stress

Example — soak only jitsi for 30 minutes:

SOAK_CARRIERS=jitsi SOAK_DURATION=30m mage soak

Updating the Binary

A running process does not update itself. To apply new code:

1. Pull the latest source

cd olcrtc
git pull --recurse-submodules

To switch branches first:

git switch dev
git pull --recurse-submodules

2. Rebuild

mage build
# Result: build/olcrtc-linux-amd64

For a different architecture, or to rebuild everything:

mage cross
ls build/

3. Stop the old process

If running in a terminal, press Ctrl+C. If running in the background:

pgrep -af olcrtc   # find the PID
kill <pid>

If using systemd, a service restart is sufficient — no manual kill needed.

4. (Optional) Install to a system path

If you copied the binary outside of build/, update the copy:

sudo install -m 0755 build/olcrtc-linux-amd64 /usr/local/bin/olcrtc

5. Restart with the same config

./build/olcrtc-linux-amd64 server.yaml
./build/olcrtc-linux-amd64 client.yaml

Or via systemd:

sudo systemctl restart olcrtc-server
sudo systemctl restart olcrtc-client

No config changes are needed if auth.provider, net.transport, room.id, crypto.key, and socks.port are unchanged.

Multiple Instances on One Server

Run as many olcRTC server instances as needed — each uses its own YAML file and runs in its own process.

# server-jitsi.yaml
mode: srv
auth:
  provider: jitsi
room:
  id: "https://meet.example.org/room1"
crypto:
  key: "aaaa...1111"
net:
  transport: datachannel
  dns: "8.8.8.8:53"
data: data

# server-wbstream.yaml
mode: srv
auth:
  provider: wbstream
room:
  id: "<room-id>"
crypto:
  key: "bbbb...2222"
net:
  transport: vp8channel
  dns: "8.8.8.8:53"
data: data

Run each in its own terminal, tmux pane, or systemd service:

./build/olcrtc-linux-amd64 server-jitsi.yaml
./build/olcrtc-linux-amd64 server-wbstream.yaml

On the client, use a different SOCKS5 port for each server:

# client-jitsi.yaml
mode: cnc
auth:
  provider: jitsi
room:
  id: "https://meet.example.org/room1"
crypto:
  key: "aaaa...1111"
net:
  transport: datachannel
  dns: "8.8.8.8:53"
socks:
  host: "127.0.0.1"
  port: 8808
data: data

# client-wbstream.yaml
mode: cnc
auth:
  provider: wbstream
room:
  id: "<room-id>"
crypto:
  key: "bbbb...2222"
net:
  transport: vp8channel
  dns: "8.8.8.8:53"
socks:
  host: "127.0.0.1"
  port: 8809
data: data

./build/olcrtc-linux-amd64 client-jitsi.yaml      # SOCKS5 on :8808
./build/olcrtc-linux-amd64 client-wbstream.yaml    # SOCKS5 on :8809

Get Started

Configuration

Reference

Integrations

Build olcRTC Natively from Source with Go 1.26+ and Mage

SWAP Recommendation

Build and Run

All Mage Targets

Build

Code Quality

Tests

Pipelines

Help

E2E Environment Variables

Updating the Binary

1. Pull the latest source

2. Rebuild

3. Stop the old process

4. (Optional) Install to a system path

5. Restart with the same config

Multiple Instances on One Server

Build docs developers (and LLMs) love

Get Started

Configuration

Reference

Integrations

Documentation Index

​SWAP Recommendation

​Build and Run

​All Mage Targets

​Build

​Code Quality

​Tests

​Pipelines

​Help

​E2E Environment Variables

​Updating the Binary

​1. Pull the latest source

​2. Rebuild

​3. Stop the old process

​4. (Optional) Install to a system path

​5. Restart with the same config

​Multiple Instances on One Server

Build docs developers (and LLMs) love

SWAP Recommendation

Build and Run

All Mage Targets

Build

Code Quality

Tests

Pipelines

Help

E2E Environment Variables

Updating the Binary

1. Pull the latest source

2. Rebuild

3. Stop the old process

4. (Optional) Install to a system path

5. Restart with the same config

Multiple Instances on One Server