vibetunnel/docs/WEBRTC_CONFIG.md

WebRTC Configuration Guide

VibeTunnel uses WebRTC for screen sharing functionality. This guide explains how to configure STUN and TURN servers for optimal performance.

Overview

WebRTC requires ICE (Interactive Connectivity Establishment) servers to establish peer-to-peer connections, especially when clients are behind NATs or firewalls.

• STUN servers: Help discover your public IP address
• TURN servers: Relay traffic when direct connection is not possible

Default Configuration

By default, VibeTunnel uses free public STUN servers from Google:

stun:stun.l.google.com:19302
stun:stun1.l.google.com:19302
stun:stun2.l.google.com:19302
stun:stun3.l.google.com:19302
stun:stun4.l.google.com:19302

Environment Variables

You can configure WebRTC servers using environment variables:

TURN Server Configuration

# Basic TURN server
export TURN_SERVER_URL="turn:turnserver.example.com:3478"
export TURN_USERNAME="myusername"
export TURN_CREDENTIAL="mypassword"

# TURN server with TCP
export TURN_SERVER_URL="turn:turnserver.example.com:3478?transport=tcp"

# TURNS (TURN over TLS)
export TURN_SERVER_URL="turns:turnserver.example.com:5349"

Additional STUN Servers

# Add custom STUN servers (comma-separated)
export ADDITIONAL_STUN_SERVERS="stun:stun.example.com:3478,stun:stun2.example.com:3478"

ICE Transport Policy

# Force all traffic through TURN server (useful for testing)
export ICE_TRANSPORT_POLICY="relay"

Programmatic Configuration

For advanced use cases, you can provide configuration programmatically:

Browser (via global variable)

window.__WEBRTC_CONFIG__ = {
  iceServers: [
    { urls: 'stun:stun.example.com:3478' },
    {
      urls: 'turn:turn.example.com:3478',
      username: 'user',
      credential: 'pass'
    }
  ]
};

Server API

The server exposes an endpoint to retrieve the current WebRTC configuration:

GET /api/webrtc-config

Response:

{
  "success": true,
  "config": {
    "iceServers": [
      { "urls": "stun:stun.l.google.com:19302" },
      {
        "urls": "turn:turn.example.com:3478",
        "username": "user",
        "credential": "pass"
      }
    ],
    "bundlePolicy": "max-bundle",
    "rtcpMuxPolicy": "require"
  }
}

Setting Up Your Own TURN Server

For production use, especially in corporate environments, you should run your own TURN server.

Using coturn

1. Install coturn:

# Ubuntu/Debian
sudo apt-get install coturn

# macOS
brew install coturn

2. Configure coturn (/etc/turnserver.conf):

# Network settings
listening-port=3478
tls-listening-port=5349
external-ip=YOUR_PUBLIC_IP

# Authentication
lt-cred-mech
user=vibetunnel:secretpassword

# Security
fingerprint
no-tlsv1
no-tlsv1_1

# Logging
log-file=/var/log/turnserver.log

3. Start the TURN server:

sudo systemctl start coturn

4. Configure VibeTunnel:

export TURN_SERVER_URL="turn:your-server.com:3478"
export TURN_USERNAME="vibetunnel"
export TURN_CREDENTIAL="secretpassword"

Troubleshooting

Connection Issues

1. Check ICE gathering state in browser console:

   // In DevTools console while screen sharing
   peerConnection.iceGatheringState
   

2. Test STUN/TURN connectivity:

   • Use online tools like: https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/
   • Enter your TURN server details and test

3. Common issues:

   • Firewall blocking UDP ports (try TCP transport)
   • TURN server authentication failures
   • Incorrect external IP configuration

Performance Optimization

1. Use geographically close servers: Deploy TURN servers near your users
2. Monitor bandwidth usage: TURN servers relay all traffic
3. Consider using TURNS (TURN over TLS) for better firewall traversal
4. Set appropriate bandwidth limits in coturn configuration

Security Considerations

1. Always use authentication for TURN servers (they relay traffic)
2. Rotate credentials regularly
3. Monitor TURN server usage for abuse
4. Use TLS for signaling (wss:// instead of ws://)
5. Restrict TURN server access by IP if possible

Example Configurations

Corporate Network with Firewall

# Use TCP transport and TURNS
export TURN_SERVER_URL="turns:turn.company.com:443?transport=tcp"
export TURN_USERNAME="corp-user"
export TURN_CREDENTIAL="secure-password"
export ICE_TRANSPORT_POLICY="relay"  # Force all traffic through TURN

High Availability Setup

window.__WEBRTC_CONFIG__ = {
  iceServers: [
    // Multiple STUN servers
    { urls: 'stun:stun1.company.com:3478' },
    { urls: 'stun:stun2.company.com:3478' },
    
    // Multiple TURN servers for redundancy
    {
      urls: [
        'turn:turn1.company.com:3478',
        'turn:turn2.company.com:3478'
      ],
      username: 'user',
      credential: 'pass'
    }
  ]
};

Development/Testing

# Simple configuration for local testing
export TURN_SERVER_URL="turn:localhost:3478"
export TURN_USERNAME="test"
export TURN_CREDENTIAL="test"

Monitoring

Monitor your WebRTC connections by checking:

1. ICE connection state: Should be "connected" or "completed"
2. Packet loss: Should be < 1% for good quality
3. Round trip time: Should be < 150ms for good experience
4. Bandwidth usage: Monitor if using TURN relay

The VibeTunnel statistics panel shows these metrics during screen sharing.