Gateway Architecture

The Gateway is Clawdbot's core component, functioning as a single daemon that manages all messaging interfaces.

Overview

The Gateway is the control center for the entire system:

• Single Entry Point: All channel connections go through the gateway
• Message Routing: Distributes messages to the correct agent
• State Management: Maintains all session and connection states
• WebSocket API: Provides real-time communication interface

Connection Model

Clients and nodes connect to the gateway via WebSocket:

┌────────────┐     WebSocket     ┌─────────────┐
│   Client   │ ◄──────────────► │   Gateway   │
│ (Dashboard)│                  │             │
└────────────┘                   └──────┬──────┘
                                        │
┌────────────┐     WebSocket            │
│    Node    │ ◄────────────────────────┘
│            │
└────────────┘

Message Protocol

Request-response format:

// Request
{type: "req", id: "1", method: "status", params: {}}
 
// Response
{type: "res", id: "1", ok: true, payload: {...}}
 
// Error response
{type: "res", id: "1", ok: false, error: "message"}

Architectural Principles

One Gateway Per Host

Each host runs one gateway instance, controlling all channel connections on that host.

# Start gateway
clawdbot gateway run

Device-Based Pairing

Nodes connect by explicitly declaring their role and capabilities:

{
  role: "node",
  capabilities: ["browser", "shell", "media"]
}

Local Trust Model

• Same-host connections: Auto-approved
• Remote connections: Require challenge signature verification

Gateway Configuration

{
  gateway: {
    // Bind address
    bind: "127.0.0.1:18789",
 
    // Authentication token (optional)
    token: "your-secure-token",
 
    // Heartbeat interval (milliseconds)
    heartbeat: 30000,
 
    // Maximum connections
    maxConnections: 100
  }
}

Remote Access

Recommended: Tailscale VPN

{
  gateway: {
    bind: "0.0.0.0:18789",
    token: "your-secure-token"
  }
}

Access the gateway via Tailscale IP.

SSH Tunnel

ssh -L 18789:127.0.0.1:18789 user@server

Security Layers

Authentication Mechanisms

1. Token Validation: Via CLAWDBOT_GATEWAY_TOKEN environment variable or config
2. Device Identity Verification: Through pairing and challenge signatures
3. Pairing Approval: New devices require manual approval

Network Security

• Default binding to loopback (127.0.0.1)
• TLS support (via reverse proxy)
• VPN recommended for remote access

Command Reference

# Run in foreground
clawdbot gateway run
 
# Run as service
clawdbot gateway install
clawdbot gateway start
clawdbot gateway stop
clawdbot gateway restart
 
# Status check
clawdbot gateway status

Health Checks

# Basic status
clawdbot status
 
# Deep check
clawdbot status --deep
 
# Live logs
clawdbot logs --follow

Next Steps

• Multi-Agent Routing - Configure multiple agents
• Session Management - Understand session mechanisms