Skip to main content

​
Overview

The zeroclaw gateway command starts the HTTP/WebSocket gateway server that accepts:
  • Webhook events from external services
  • WebSocket connections for real-time communication
  • API requests for programmatic control
The gateway enables remote interaction with your ZeroClaw agent through various channels.

​
Basic Usage

# Start with config defaults
zeroclaw gateway

# Start on specific port
zeroclaw gateway -p 8080

# Bind to all interfaces
zeroclaw gateway --host 0.0.0.0

​
Command Syntax

zeroclaw gateway [OPTIONS]

​
Options

​
-p, --port
integer
Port to listen on. Use 0 for random available port. Defaults to gateway.port in config (typically 8585).
​
--host
string
Host address to bind to. Defaults to gateway.host in config (typically 127.0.0.1).Common values:
  • 127.0.0.1 - Localhost only (secure default)
  • 0.0.0.0 - All interfaces (public access)
  • Specific IP - Bind to specific network interface
​
--new-pairing
boolean
Clear all paired tokens and generate a fresh pairing code. Use this to reset gateway authentication.

​
Examples

​
Basic Gateway

# Use config defaults (127.0.0.1:8585)
zeroclaw gateway

# Specific port
zeroclaw gateway -p 8080

# Random available port
zeroclaw gateway -p 0

​
Network Configuration

# Localhost only (secure default)
zeroclaw gateway --host 127.0.0.1 -p 8585

# Accept connections from local network
zeroclaw gateway --host 0.0.0.0 -p 8585

# Bind to specific interface
zeroclaw gateway --host 192.168.1.100 -p 8585

​
Security Operations

# Generate new pairing code
zeroclaw gateway --new-pairing

# Reset tokens and start fresh
zeroclaw gateway --new-pairing -p 8080

​
Terminal Output

$ zeroclaw gateway
🚀 Starting ZeroClaw Gateway on 127.0.0.1:8585

🔐 Pairing Code: WXYZ-1234-ABCD
   Use this code to authenticate new clients
   Valid for: 15 minutes

✓ Gateway server started
  HTTP:  http://127.0.0.1:8585
  WebSocket: ws://127.0.0.1:8585/ws

📡 Listening for webhook events...

​
With New Pairing

$ zeroclaw gateway --new-pairing
🔐 Cleared paired tokens — a fresh pairing code will be generated
🚀 Starting ZeroClaw Gateway on 127.0.0.1:8585

🔐 New Pairing Code: EFGH-5678-IJKL
   Use this code to authenticate new clients
   Valid for: 15 minutes

✓ Gateway server started

​
Random Port

$ zeroclaw gateway -p 0
🚀 Starting ZeroClaw Gateway on 127.0.0.1 (random port)

✓ Gateway server started on port: 54321
  HTTP:  http://127.0.0.1:54321
  WebSocket: ws://127.0.0.1:54321/ws

🔐 Pairing Code: MNOP-9012-QRST

​
Gateway Features

​
HTTP Endpoints

The gateway exposes these HTTP endpoints:
  • POST /webhook - Receive webhook events
  • POST /api/message - Send messages to agent
  • GET /api/status - Gateway health check
  • GET /health - System health status

​
WebSocket Protocol

Connect to /ws for real-time bidirectional communication: 
const ws = new WebSocket('ws://127.0.0.1:8585/ws');

ws.on('open', () => {
  ws.send(JSON.stringify({
    type: 'message',
    content: 'Hello from client',
    token: 'your-pairing-token'
  }));
});

ws.on('message', (data) => {
  const response = JSON.parse(data);
  console.log('Agent response:', response);
});

​
Security Features

  • Pairing codes - Time-limited codes for client authentication
  • Token-based auth - Paired tokens for ongoing sessions
  • Request limits - 64KB max request body size
  • Timeouts - 30s request timeout to prevent slow-loris attacks
  • Rate limiting - Per-client rate limits (60s sliding window)
  • Idempotency - Duplicate request detection

​
Configuration

Gateway settings in config.toml: 
[gateway]
host = "127.0.0.1"  # Bind address
port = 8585          # Listen port
paired_tokens = []   # Authenticated tokens (managed automatically)

[gateway.rate_limit]
enabled = true
max_requests_per_window = 60
window_seconds = 60
max_tracked_keys = 10000

[gateway.idempotency]
enabled = true
max_keys = 10000

​
Integration with Channels

The gateway works with various channel integrations:
  • WhatsApp - Webhook endpoint for WhatsApp Business API
  • GitHub - Webhook receiver for repository events
  • Custom webhooks - Generic webhook receiver for any service

​
Security Best Practices

Never bind to 0.0.0.0 on public servers without additional security (firewall rules, reverse proxy, VPN).
  1. Local development: Use default 127.0.0.1
  2. Remote access: Use SSH tunnel or VPN
  3. Production: Place behind reverse proxy (nginx, Caddy) with TLS

​
Pairing Token Management

# Rotate tokens periodically
zeroclaw gateway --new-pairing

# Monitor paired tokens in config
zeroclaw config get gateway.paired_tokens

​
Troubleshooting

​
Port Already in Use

# Check what's using the port
lsof -i :8585

# Use different port
zeroclaw gateway -p 9090

# Or use random port
zeroclaw gateway -p 0

​
Can’t Connect from Remote Host

# Check current binding
zeroclaw config get gateway.host

# Bind to all interfaces (be careful!)
zeroclaw gateway --host 0.0.0.0

# Better: Use SSH tunnel
ssh -L 8585:localhost:8585 user@remote-host

​
Pairing Code Expired

# Pairing codes expire after 15 minutes
# Restart gateway to generate new code
zeroclaw gateway --new-pairing

​
Exit Codes

  • 0 - Success (gateway stopped gracefully)
  • 1 - Startup error (port in use, permission denied)
  • 2 - Configuration error
  • 130 - Interrupted (Ctrl+C)

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us