Guide

TunnelCrib Relay guide

TunnelCrib Relay is fallback transport infrastructure for Tunnels that cannot connect directly between a TunnelCrib Client and a TunnelCrib Agent. A customer-operated Relay is a Private Relay. Its executable is tunnelcrib-relay; it launches a per-session tunnelcrib-bridge process for each active Tunnel.

1. Prepare the relay host

  1. Download the tunnelcrib-relay binary for the host OS and architecture.
  2. Place the matching tunnelcrib-bridge binary alongside it, or configure an absolute TUNNELCRIB_BRIDGE_BIN path.
  3. Run the node as an unprivileged service account.
  4. Allow outbound WSS traffic to the TunnelCrib WebSocket server.
  5. Allow inbound TCP traffic for the configured Relay port range from TunnelCrib Client and TunnelCrib Agent.
Public endpoint: PUBLIC_HOST must be a public DNS name or IP address reachable by both TunnelCrib Client and TunnelCrib Agent. It must not be a private LAN-only address.

2. Register a Private Relay (one-time setup)

./tunnelcrib-relay --register <domain> <orgid> <registration-token>

Registration creates a persistent Relay Device identity and registers its public key with the organization. Normal startup automatically uses Private Relay mode after registration.

The identity and registration configuration are stored in the platform configuration directory, such as ~/.config/tunnelcrib/relay/ on Linux (or the platform equivalent under Go's os.UserConfigDir()).

3. Run a Private Relay

PUBLIC_HOST=relay.example.com \
RELAY_PORT_START=1337 \
RELAY_PORT_END=2337 \
MAX_SESSIONS=10 \
TUNNELCRIB_BRIDGE_BIN=/opt/tunnelcrib/tunnelcrib-bridge \
./tunnelcrib-relay

The Relay authenticates to the WebSocket server using its registered Ed25519 key, sends a heartbeat every 30 seconds, and accepts Tunnels only for its organization.

4. Private Relay environment

VariableDefaultDescription
PUBLIC_HOSTlocalhostPublic hostname or IP sent to TunnelCrib Client and TunnelCrib Agent.
RELAY_PORT_START1337First inbound relay port.
RELAY_PORT_END2337Last inbound relay port.
MAX_SESSIONS10Maximum concurrent tunnelcrib-bridge processes.
TUNNELCRIB_BRIDGE_BIN./tunnelcrib-bridgePath to the TunnelCrib Bridge binary.
TS_LOGunsetSet to DEBUG for verbose logs.

5. TunnelCrib-hosted Relay mode

Trusted TunnelCrib infrastructure can still run this same binary in a non-Private-Relay mode. This mode is not organization-scoped and should not be used for a Private Relay.

WS_URL=wss://ws.example.com \
WS_TOKEN=<orgid> \
PUBLIC_HOST=platform-relay.example.com \
./tunnelcrib-relay
Do not run this mode on a host that already has Private Relay registration state. Use --customer to explicitly require Private Relay mode when configuring a new host with WS_URL and WS_TOKEN.

6. Operational checks

  1. Confirm the node logs successful WebSocket registration.
  2. Confirm the central server sees the Private Relay as healthy.
  3. Verify the firewall permits the entire configured relay range.
  4. Test a direct-Tunnel-unavailable connection; TunnelCrib should select the Private Relay when it is online.
  5. Stop the Relay and repeat the test; TunnelCrib should use a TunnelCrib-hosted Relay instead.

Last reviewed 2026-09-09 against the current CLI source. Corrections are welcome — support@gaur.is.