Gateway Hardening Guide

The Moltbot gateway is the primary interface between external requests and your AI agent. Proper hardening is essential to prevent unauthorized access and limit potential damage from compromised sessions.

Gateway Architecture Overview

┌─────────────────────────────────────────────┐
│                 Internet                     │
└─────────────────┬───────────────────────────┘
                  │
        ┌─────────▼─────────┐
        │  Authentication   │  ← Token/Password
        │      Layer        │
        └─────────┬─────────┘
                  │
        ┌─────────▼─────────┐
        │   Gateway Server  │  ← Port Binding
        │                   │
        └─────────┬─────────┘
                  │
        ┌─────────▼─────────┐
        │   Moltbot Agent   │  ← Tool Permissions
        │                   │
        └─────────┬─────────┘
                  │
        ┌─────────▼─────────┐
        │  Your System      │  ← File/Process Access
        └───────────────────┘

Critical Security Settings

Authentication Modes

Moltbot supports multiple authentication methods. Choose based on your security requirements:

Token Authentication (Recommended)

{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "your-secure-random-token-here",
      "tokenRotation": "30d"
    }
  }
}

Generate a strong token:

openssl rand -hex 32

Best practices:

• Use at least 256-bit (32 byte) random tokens
• Rotate tokens every 30 days
• Never commit tokens to version control
• Use environment variables for token storage

Password Authentication

{
  "gateway": {
    "auth": {
      "mode": "password",
      "passwordHash": "$argon2id$v=19$m=65536,t=3,p=4$..."
    }
  }
}

Generate password hash:

moltbot auth hash-password

DM Pairing & Allowlists

Control who can interact with your agent:

{
  "gateway": {
    "dmPolicies": {
      "enabled": true,
      "allowlist": [
        "user@example.com",
        "team-lead@company.com"
      ],
      "denyByDefault": true
    }
  }
}

Key settings:

• denyByDefault: true - Block all users not in allowlist
• Regularly audit the allowlist
• Remove former team members immediately

Group Policies

For team environments:

{
  "gateway": {
    "groupPolicies": {
      "enabled": true,
      "allowedGroups": ["engineering", "security"],
      "mentionGating": true
    }
  }
}

Plugin Management

Disable unnecessary plugins to reduce attack surface:

{
  "plugins": {
    "enabled": ["core", "git"],
    "disabled": ["puppeteer", "experimental"],
    "trustLevel": "verified-only"
  }
}

File Permissions Hardening

Proper file permissions prevent unauthorized access to sensitive configuration:

Configuration Files

# Apply secure permissions
chmod 600 ~/.config/moltbot/config.json
chmod 600 ~/.config/moltbot/auth.json
chmod 600 ~/.config/moltbot/*.key

Directories

# Secure directories
chmod 700 ~/.config/moltbot/
chmod 700 ~/.local/share/moltbot/

Symlink Risks

Symlinks can be exploited to access files outside intended directories:

# Check for suspicious symlinks
find ~/.config/moltbot -type l -ls

# Disable symlink following in config
{
  "security": {
    "followSymlinks": false
  }
}

Network Security

Local vs Remote Binding

Local only (most secure):

{
  "gateway": {
    "bind": "127.0.0.1",
    "port": 8080
  }
}

LAN access:

{
  "gateway": {
    "bind": "192.168.1.100",
    "port": 8080
  }
}

⚠️ Never bind to 0.0.0.0 without proper authentication!

Tailscale Integration (Recommended for Remote Access)

Instead of exposing ports publicly, use Tailscale:

# Install Tailscale
curl -fsSL https://tailscale.com/install.sh | sh

# Serve your gateway
tailscale serve https / http://127.0.0.1:8080

# Or use Tailscale Funnel for public access with auth
tailscale funnel 8080

Benefits:

• End-to-end encryption
• Zero-trust network access
• Automatic certificate management
• Access logs and audit trail

Firewall Rules

# Allow only local access
sudo ufw allow from 127.0.0.1 to any port 8080

# For Tailscale, allow the interface
sudo ufw allow in on tailscale0

Configuration Templates

Minimal Secure Configuration

{
  "gateway": {
    "bind": "127.0.0.1",
    "port": 8080,
    "auth": {
      "mode": "token",
      "token": "${MOLTBOT_TOKEN}"
    },
    "dmPolicies": {
      "enabled": true,
      "denyByDefault": true,
      "allowlist": []
    }
  },
  "security": {
    "followSymlinks": false,
    "maxRequestSize": "10MB",
    "rateLimiting": {
      "enabled": true,
      "requestsPerMinute": 60
    }
  },
  "plugins": {
    "trustLevel": "verified-only"
  }
}

Team/Production Configuration

{
  "gateway": {
    "bind": "127.0.0.1",
    "port": 8080,
    "auth": {
      "mode": "token",
      "token": "${MOLTBOT_TOKEN}",
      "tokenRotation": "7d"
    },
    "dmPolicies": {
      "enabled": true,
      "denyByDefault": true,
      "allowlist": ["${TEAM_EMAILS}"]
    },
    "groupPolicies": {
      "enabled": true,
      "mentionGating": true
    }
  },
  "security": {
    "followSymlinks": false,
    "auditLogging": true,
    "maxRequestSize": "50MB",
    "rateLimiting": {
      "enabled": true,
      "requestsPerMinute": 120
    }
  },
  "plugins": {
    "enabled": ["core", "git", "testing"],
    "trustLevel": "verified-only"
  },
  "monitoring": {
    "enabled": true,
    "endpoint": "${MONITORING_URL}"
  }
}

Verification Steps

After configuration, verify your hardening:

# 1. Run security audit
moltbot security audit

# 2. Check file permissions
ls -la ~/.config/moltbot/

# 3. Test authentication
curl -H "Authorization: Bearer wrong-token" http://127.0.0.1:8080/health
# Should return 401 Unauthorized

# 4. Verify binding
netstat -tlnp | grep 8080
# Should show 127.0.0.1:8080, not 0.0.0.0:8080

# 5. Check for open ports
nmap -p 8080 your-server-ip
# Should show filtered/closed if properly configured

Common Mistakes

❌ Mistake 1: Default Tokens

Never use example tokens from documentation.

❌ Mistake 2: World-Readable Config

Config files should be 600, not 644.

❌ Mistake 3: Binding to 0.0.0.0

Use 127.0.0.1 and a secure tunnel instead.

❌ Mistake 4: No Token Rotation

Rotate authentication tokens regularly.

❌ Mistake 5: Empty Allowlists with denyByDefault: false

This allows anyone to connect.

Recommended Hosting

For production gateway deployments, a dedicated VPS provides better isolation than running on your development machine.

Digital Ocean Droplets offer:

• One-click firewall configuration
• Private networking
• Monitoring and alerts
• Starting at $4/month

---

Next: Security Audit Checklist - Interactive tool to audit your configuration