Docs / Web Gateway
⭐ Star
🌐 Features

Web Gateway

Remote management via REST API and WebSocket for real-time monitoring.

🚀 Quick Start

# Start gateway server
orcbot gateway

# Start with agent loop
orcbot gateway --with-agent

# Custom port and static dashboard
orcbot gateway -p 8080 -s ./apps/dashboard

📡 REST API Endpoints

MethodEndpointDescription
GET/api/statusAgent status and current action
GET/api/doctorHealth report including runtime lock/PID checks
GET/api/security/auditFiltered security and gateway audit report
GET/api/skillsList all registered skills
POST/api/tasksPush a new task to the queue
GET/api/configView current configuration
GET/api/memoryView recent memories
GET/api/connectionsChannel connection status
GET/api/logsRecent log entries
GET/api/orchestrator/agentsList spawned agents
POST/api/tasks/:id/cancelCancel a pending task

🔌 WebSocket Events

Connect to ws://localhost:3100 for real-time updates:

Incoming Events

// Status update
{ "type": "status", "data": { "status": "busy", "currentAction": {...} } }

// Log entry
{ "type": "log", "data": { "level": "info", "message": "..." } }

// Memory added
{ "type": "memory", "data": { "id": "...", "content": "..." } }

Outgoing Commands

// Push task via WebSocket
{ "action": "push_task", "task": "Search for X", "priority": 8 }

// Chat message
{ "action": "chat", "message": "Hello OrcBot!" }

// Cancel task
{ "action": "cancel_task", "taskId": "abc123" }

🔐 Authentication

Set an API key for authentication:

# In config
gatewayApiKey: your-secret-key

# In requests
curl -H "X-Api-Key: your-secret-key" http://localhost:3100/api/status

🛡️ Security Model

  • The gateway is an operator-facing control plane, not a public chat endpoint. Do not expose it on a public interface without gatewayApiKey and restricted CORS.
  • Clients should send a stable sourceId or clientId so OrcBot can keep messages in the correct session scope and route follow-ups deterministically.
  • Worker processes do not reply to gateway clients directly. Delegated task results return through the primary agent, which preserves the original reply context.
  • Use /api/doctor and /api/security/audit to verify runtime state, stale lock files, gateway exposure, and security posture before enabling remote access.

🧭 Gateway Chat Routing

Inbound gateway chat follows the same deterministic routing rules as other channels:

  1. Resolve a stable thread scope from sourceId or clientId
  2. Resume an existing waiting action for that thread if one exists
  3. Fail stale pending thread actions so they cannot run after a newer user message
  4. Queue behind an active in-progress thread action when necessary
  5. Route worker completions back through the originating gateway chat thread

This keeps web-chat sessions aligned with Telegram, WhatsApp, Discord, Slack, and Email behavior instead of using a separate routing model.

📊 Dashboard

Serve the built-in dashboard for a visual interface:

orcbot gateway -s ./apps/dashboard

Then open http://localhost:3100 in your browser.