webrtc-mcp-chat/LOCAL_REVERSE_PROXY.md

A remote WebRTC chat server with secure temporary rooms and MCP support for background agents

# Local Server with Reverse Proxy

Run your WebRTC MCP Chat Server locally while making it accessible to remote background agents via reverse proxy tunnels.

## 🚀 Quick Start

### Option 1: ngrok (Recommended)

```bash
# 1. Install ngrok
brew install ngrok
# or: npm install -g ngrok

# 2. Start your local server
npm start

# 3. In another terminal, expose via ngrok
ngrok http 3000

# 4. Use the ngrok URL for your agents
export CHAT_SERVER_URL=https://abc123.ngrok.io
chat-room create --expires 60 --created-by local-agent
```

### Option 2: Cloudflare Tunnel (Free & Persistent)

```bash
# 1. Install cloudflared
brew install cloudflared
# or: Download from https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/

# 2. Start your local server
npm start

# 3. Create tunnel
cloudflared tunnel --url http://localhost:3000

# 4. Use the tunnel URL for your agents  
export CHAT_SERVER_URL=https://abc-def-ghi.trycloudflare.com
```

### Option 3: localtunnel (Simple)

```bash
# 1. Install localtunnel
npm install -g localtunnel

# 2. Start your local server
npm start

# 3. Expose via localtunnel
lt --port 3000 --subdomain mywebrtcchat

# 4. Use the tunnel URL
export CHAT_SERVER_URL=https://mywebrtcchat.loca.lt
```

## 🛠️ Enhanced Setup with npm Scripts

I'll add convenient npm scripts for common reverse proxy setups:

```bash
# Start with ngrok
npm run dev:ngrok

# Start with cloudflare tunnel
npm run dev:cloudflare

# Start with localtunnel
npm run dev:localtunnel

# Just local development
npm run dev
```

## 🔧 Configuration

### Environment Variables

Create a `.env.local` file:

```bash
# .env.local
NODE_ENV=development
REMOTE_MODE=false
LOCAL_TUNNEL_URL=https://your-tunnel-url.com
PORT=3000
```

### Automatic URL Detection

The server will automatically detect and use tunnel URLs when available.

## 🌐 Reverse Proxy Options Comparison

| Service | Pros | Cons | Best For |
|---------|------|------|----------|
| **ngrok** | Fast setup, reliable, custom domains | Rate limits on free tier | Development & testing |
| **Cloudflare Tunnel** | Free, persistent URLs, fast | Requires Cloudflare account | Production-like testing |
| **localtunnel** | Simple, no signup | Less reliable, random URLs | Quick demos |
| **serveo** | SSH-based, simple | Can be unstable | SSH users |

## 🚀 Step-by-Step Setup

### ngrok Setup (Detailed)

1. **Install ngrok**
   ```bash
   # macOS
   brew install ngrok
   
   # Windows (chocolatey)
   choco install ngrok
   
   # Or download from https://ngrok.com/download
   ```

2. **Sign up for ngrok account (optional but recommended)**
   ```bash
   ngrok authtoken YOUR_AUTH_TOKEN
   ```

3. **Start local server**
   ```bash
   npm start
   ```

4. **Create tunnel**
   ```bash
   # Basic tunnel
   ngrok http 3000
   
   # With custom subdomain (requires paid plan)
   ngrok http 3000 --subdomain mywebrtcchat
   
   # With custom domain (requires paid plan)
   ngrok http 3000 --hostname chat.yourdomain.com
   ```

5. **Configure agents**
   ```bash
   export CHAT_SERVER_URL=https://abc123.ngrok.io
   chat-room health  # Test connection
   ```

### Cloudflare Tunnel Setup (Detailed)

1. **Install cloudflared**
   ```bash
   # macOS
   brew install cloudflared
   
   # Windows
   winget install --id Cloudflare.cloudflared
   
   # Linux
   wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
   sudo dpkg -i cloudflared-linux-amd64.deb
   ```

2. **Start local server**
   ```bash
   npm start
   ```

3. **Create quick tunnel (no signup required)**
   ```bash
   cloudflared tunnel --url http://localhost:3000
   ```

4. **Or create persistent tunnel (requires Cloudflare account)**
   ```bash
   # Login to Cloudflare
   cloudflared tunnel login
   
   # Create named tunnel
   cloudflared tunnel create webrtc-chat
   
   # Configure tunnel
   cloudflared tunnel route dns webrtc-chat chat.yourdomain.com
   
   # Run tunnel
   cloudflared tunnel run webrtc-chat
   ```

## 🤖 Background Agent Examples

### Simple Agent with Tunnel

```bash
#!/bin/bash
# agent-with-tunnel.sh

# Start local server in background
npm start &
SERVER_PID=$!

# Wait for server to start
sleep 3

# Start ngrok tunnel
ngrok http 3000 --log=stdout | grep -o 'https://[^"]*\.ngrok\.io' | head -1 > tunnel_url.txt &
NGROK_PID=$!

# Wait for tunnel to establish
sleep 5

# Get tunnel URL
TUNNEL_URL=$(cat tunnel_url.txt)
export CHAT_SERVER_URL=$TUNNEL_URL

echo "🚀 Server running locally, accessible at: $TUNNEL_URL"

# Create room for agents
ROOM_INFO=$(chat-room create --expires 120 --created-by tunnel-agent --output json)
echo "📋 Room created: $(echo $ROOM_INFO | jq -r '.joinUrl')"

# Cleanup on exit
trap "kill $SERVER_PID $NGROK_PID; rm -f tunnel_url.txt" EXIT

# Keep script running
wait
```

### CI/CD with Tunnel

```yaml
# .github/workflows/test-with-tunnel.yml
name: Test with Local Tunnel
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '18'
          
      - name: Install dependencies
        run: npm install
        
      - name: Start server with tunnel
        run: |
          npm start &
          npx localtunnel --port 3000 --subdomain gh-${{ github.run_id }} &
          sleep 10
          
      - name: Test remote access
        env:
          CHAT_SERVER_URL: https://gh-${{ github.run_id }}.loca.lt
        run: |
          npx webrtc-mcp-chat health
          ROOM_INFO=$(npx webrtc-mcp-chat create --expires 5 --output json)
          echo "Test room: $(echo $ROOM_INFO | jq -r '.joinUrl')"
```

### Docker with Tunnel

```dockerfile
# Dockerfile.tunnel
FROM node:18-alpine

# Install cloudflared
RUN apk update && apk add --no-cache wget
RUN wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -O /usr/local/bin/cloudflared
RUN chmod +x /usr/local/bin/cloudflared

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY . .

# Start script that runs both server and tunnel
COPY start-with-tunnel.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/start-with-tunnel.sh

EXPOSE 3000
CMD ["start-with-tunnel.sh"]
```

```bash
#!/bin/bash
# start-with-tunnel.sh

# Start the chat server in background
npm start &

# Start cloudflare tunnel
cloudflared tunnel --url http://localhost:3000 &

# Wait for both processes
wait
```

## 🔒 Security Considerations

### Tunnel Security

1. **Use HTTPS tunnels** (all options provide this)
2. **Limit tunnel lifetime** for sensitive operations
3. **Use authentication tokens** where available
4. **Monitor tunnel logs** for unusual activity

### Local Server Security

```bash
# Bind to localhost only (default)
SERVER_HOST=127.0.0.1 npm start

# Use temporary rooms for sensitive data
chat-room create --expires 15 --created-by secure-agent
```

## 📊 Monitoring Tunnels

### Health Check Script

```bash
#!/bin/bash
# check-tunnel-health.sh

TUNNEL_URL=$1
if [ -z "$TUNNEL_URL" ]; then
    echo "Usage: $0 <tunnel-url>"
    exit 1
fi

echo "🔍 Checking tunnel health: $TUNNEL_URL"

# Test basic connectivity
if curl -sf "$TUNNEL_URL/health" > /dev/null; then
    echo "✅ Tunnel is healthy"
    
    # Test chat functionality
    export CHAT_SERVER_URL=$TUNNEL_URL
    if chat-room health > /dev/null 2>&1; then
        echo "✅ Chat server accessible through tunnel"
    else
        echo "❌ Chat server not accessible through tunnel"
        exit 1
    fi
else
    echo "❌ Tunnel is not responding"
    exit 1
fi
```

### Tunnel Monitoring with Uptime

```bash
#!/bin/bash
# monitor-tunnel.sh

TUNNEL_URL=$1
CHECK_INTERVAL=30

while true; do
    if curl -sf "$TUNNEL_URL/health" > /dev/null; then
        echo "$(date): ✅ Tunnel healthy"
    else
        echo "$(date): ❌ Tunnel down - restarting..."
        # Add your tunnel restart logic here
        pkill ngrok
        ngrok http 3000 &
        sleep 10
    fi
    sleep $CHECK_INTERVAL
done
```

## 🚀 Quick Commands Reference

```bash
# Start with different tunnels
npm run dev:ngrok      # Start server + ngrok
npm run dev:cloudflare # Start server + cloudflare tunnel  
npm run dev:localtunnel # Start server + localtunnel

# Health checks
chat-room health                    # Check via tunnel
curl $CHAT_SERVER_URL/health       # Direct health check

# Create temporary rooms
chat-room create --expires 60      # 1 hour room
chat-room create --expires 1440    # 24 hour room

# Agent communication
chat-room join <room> <token> <user>
chat-room send <room> <token> <user> "message"
```

## 💡 Pro Tips

1. **Use ngrok for development** - most reliable and feature-rich
2. **Use Cloudflare Tunnel for demos** - free persistent URLs
3. **Use localtunnel for quick tests** - no signup required
4. **Monitor tunnel health** - tunnels can disconnect
5. **Use temporary rooms** - perfect for tunnel-based workflows
6. **Keep tunnel URLs secure** - they provide direct access to your local server

## 🔧 Troubleshooting

### Common Issues

**Tunnel URL not accessible**
```bash
# Check if tunnel is running
ps aux | grep ngrok
# Check tunnel status
curl -sf http://localhost:4040/api/tunnels  # ngrok status
```

**Server not responding through tunnel**
```bash
# Check local server
curl http://localhost:3000/health
# Check tunnel forwarding
curl $TUNNEL_URL/health
```

**Background agents can't connect**
```bash
# Verify environment variable
echo $CHAT_SERVER_URL
# Test from agent machine
chat-room health
```

**ngrok browser warning issues**
```bash
# If you see ngrok browser warnings, the tools automatically handle this
# The 'ngrok-skip-browser-warning' header is added automatically
# when URLs contain 'ngrok' or 'ngrok-free.app'

# Manual test with curl:
curl -H "ngrok-skip-browser-warning: true" $NGROK_URL/health
```

This setup gives you the perfect balance: **local development** with **remote accessibility** for your background agents! 🚀