When do I need a reverse proxy?

When you need HTTPS access to the Gateway from external networks, multiple services sharing ports 80/443, load balancing across multiple Gateway instances, or additional security layers.

What to do if connection drops after 60 seconds?

Increase proxy timeouts. WebSocket connections should stay open for hours - adjust proxy_read_timeout and proxy_send_timeout values.

Moltbot Reverse Proxy Setup

For most Moltbot setups, you don't need a reverse proxy. The Gateway uses outbound WebSocket connections to messaging platforms, which work behind NAT and firewalls.

However, a reverse proxy is useful when you need:

HTTPS access to the Gateway from external networks
Multiple services sharing ports 80/443
Load balancing across multiple Gateway instances
Additional security layers

When You Need a Reverse Proxy

Scenario	Need Reverse Proxy?
Local macOS app	No
Single Linux server	Usually no
Gateway behind corporate firewall	Maybe
Public-facing admin dashboard	Yes
Kubernetes/cloud deployment	Yes

TL;DR

Caddy (Recommended):

caddy reverse-proxy --from moltbot.your-domain.com --to localhost:18789

Nginx:

location / {
    proxy_pass http://localhost:18789;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Prerequisites

Domain name pointing to your server
Moltbot Gateway running on localhost:18789
Root/sudo access (for ports 80/443)

Option A: Caddy (Recommended)

Caddy handles HTTPS automatically with zero configuration.

Install Caddy

# Ubuntu/Debian
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Configure Caddy

Create /etc/caddy/Caddyfile:

moltbot.your-domain.com {
    reverse_proxy localhost:18789
}

Start Caddy

sudo systemctl enable caddy
sudo systemctl start caddy

Caddy automatically obtains and renews SSL certificates.

Option B: Nginx

Install Nginx

sudo apt install nginx certbot python3-certbot-nginx

Configure Nginx

Create /etc/nginx/sites-available/moltbot:

server {
    listen 80;
    server_name moltbot.your-domain.com;

    location / {
        proxy_pass http://localhost:18789;
        proxy_http_version 1.1;

        # WebSocket support (required for Gateway)
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Standard proxy headers
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Timeouts for long-running connections
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 3600s;
    }
}

Enable Site and Get SSL

sudo ln -s /etc/nginx/sites-available/moltbot /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d moltbot.your-domain.com

WebSocket Configuration

The Gateway uses WebSocket for real-time communication. Ensure your reverse proxy:

Passes Upgrade headers - Required for WebSocket handshake
Maintains long connections - Don't time out active WebSocket connections
Doesn't buffer - Stream responses in real-time

Nginx WebSocket Config

# In the location block
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;  # Keep connections alive for 1 hour
proxy_buffering off;

Caddy WebSocket Config

Caddy handles WebSocket automatically - no special configuration needed.

Connecting Through the Proxy

Update your config to use the proxied URL:

{
  "gateway": {
    "externalUrl": "wss://moltbot.your-domain.com"
  }
}

Or when connecting the macOS app:

Settings → Connection
Mode: Remote
URL: wss://moltbot.your-domain.com

Common Issues

WebSocket Connection Fails

Check that Upgrade and Connection headers are being passed through. Test with:

curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
  https://moltbot.your-domain.com/

Connection Drops After 60 Seconds

Increase proxy timeouts. WebSocket connections should stay open for hours.

SSL Certificate Error

Ensure DNS is pointing to your server before requesting certificates. Check with:

dig +short moltbot.your-domain.com

Security Considerations

Use HTTPS (both Caddy and Nginx + Certbot handle this)
Consider IP allowlisting for admin access
Enable rate limiting to prevent abuse
Keep proxy software updated

Rate Limiting (Nginx)

limit_req_zone $binary_remote_addr zone=moltbot:10m rate=10r/s;

server {
    location / {
        limit_req zone=moltbot burst=20 nodelay;
        # ... other config
    }
}

Cloudflare Tunnel Alternative

For zero-configuration public access without managing certificates:

# Install cloudflared
brew install cloudflared
# or
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared

# Create tunnel
cloudflared tunnel --url http://localhost:18789

This gives you a public URL like https://random-words.trycloudflare.com instantly.