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.