orcbot gateway

Overview

The orcbot gateway command starts an Express-based web server that exposes OrcBot’s capabilities via REST API and WebSocket connections. It provides remote management, task queuing, and real-time event streaming.

Usage

# Start gateway on default port (3100)
orcbot gateway

# Start with custom port and host
orcbot gateway -p 8080 -h 127.0.0.1

# Start with API key authentication
orcbot gateway -k mysecretkey

# Start with static dashboard files
orcbot gateway -s ./apps/dashboard

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

# Run in background (daemon-style)
orcbot gateway --background

Options

number

default:"3100"

Port to listen on. Must be available and not used by another process.

string

default:"0.0.0.0"

Host/interface to bind to. Use 127.0.0.1 for localhost-only, 0.0.0.0 for all interfaces.

string

API key for authentication. If set, all API requests must include X-Api-Key header. Overrides gatewayApiKey config value.

string

Path to static files for web dashboard. Serves files at root /. Useful for hosting a custom frontend.

boolean

default:"false"

Also start the agent autonomous loop alongside the gateway. Allows full remote operation without separate orcbot run command.

boolean

default:"false"

Run gateway in background (detached process). Logs to ~/.orcbot/gateway.log. Stop with pkill -f "orcbot gateway --background-child".

REST API Endpoints

All endpoints are prefixed with /api.

GET /api/status

Returns agent status and system information. Response:

{
  "running": true,
  "model": "gpt-4o",
  "provider": "openai",
  "memory": {
    "short": 45,
    "episodic": 12,
    "long": 4
  },
  "queue": {
    "pending": 3,
    "failed": 0
  },
  "autonomy": {
    "enabled": true,
    "interval": 1800000
  },
  "safeMode": false,
  "version": "2.1.0"
}

GET /api/skills

List all available skills with metadata. Response:

{
  "skills": [
    {
      "name": "web_search",
      "description": "Search with API + browser fallback",
      "category": "web",
      "parameters": ["query", "maxResults"]
    },
    {
      "name": "run_command",
      "description": "Execute shell commands",
      "category": "system",
      "parameters": ["command", "args", "cwd"]
    }
  ]
}

POST /api/skills/:name/execute

Execute a specific skill with parameters. Request:

{
  "parameters": {
    "query": "latest AI news",
    "maxResults": 5
  }
}

Response:

{
  "success": true,
  "result": "Search results...",
  "executionTime": 1234
}

POST /api/tasks

Push a new task to the action queue. Request:

{
  "task": "Check Bitcoin price and save to journal",
  "priority": 8
}

Response:

{
  "success": true,
  "taskId": "act_1709548815123_abc123",
  "message": "Task queued with priority 8"
}

GET /api/tasks

View current task queue. Response:

{
  "pending": [
    {
      "id": "act_1709548815123_abc123",
      "task": "Check Bitcoin price and save to journal",
      "priority": 8,
      "status": "pending",
      "createdAt": "2026-03-04T10:30:15.123Z"
    }
  ],
  "completed": [],
  "failed": []
}

GET /api/config

View current configuration (sensitive values redacted). Response:

{
  "modelName": "gpt-4o",
  "maxStepsPerAction": 20,
  "autonomyEnabled": true,
  "openaiApiKey": "sk-***...",
  "safeMode": false
}

PUT /api/config/:key

Update a configuration value. Request:

{
  "value": "gpt-4o-mini"
}

Response:

{
  "success": true,
  "key": "modelName",
  "value": "gpt-4o-mini",
  "message": "Configuration updated"
}

GET /api/memory

Retrieve recent memories. Query params:

type: Filter by type (short, episodic, long)
limit: Max results (default: 50)
search: Keyword search

Response:

{
  "memories": [
    {
      "id": "mem_123",
      "type": "short",
      "content": "User asked about Bitcoin price",
      "timestamp": "2026-03-04T10:30:15.123Z",
      "metadata": {
        "actionId": "act_456",
        "step": 1
      }
    }
  ],
  "total": 45
}

GET /api/connections

View channel connection status. Response:

{
  "telegram": {
    "enabled": true,
    "connected": true,
    "botUsername": "my_bot",
    "botId": 123456789
  },
  "whatsapp": {
    "enabled": false,
    "connected": false
  },
  "discord": {
    "enabled": true,
    "connected": true,
    "guilds": 3
  }
}

GET /api/logs

Retrieve recent log entries. Query params:

level: Filter by level (info, warn, error)
limit: Max entries (default: 100)

Response:

{
  "logs": [
    {
      "level": "info",
      "message": "Agent loop started",
      "timestamp": "2026-03-04T10:30:15.123Z"
    },
    {
      "level": "warn",
      "message": "Rate limit approaching",
      "timestamp": "2026-03-04T10:35:20.456Z"
    }
  ]
}

GET /api/security

View security settings. Response:

{
  "safeMode": false,
  "apiKeySet": true,
  "adminUsers": ["user123"],
  "pluginAllowList": [],
  "pluginDenyList": []
}

PUT /api/security

Update security settings. Request:

{
  "safeMode": true
}

Response:

{
  "success": true,
  "message": "Security settings updated"
}

WebSocket Interface

Connect to ws://host:port for real-time events.

Connection

const ws = new WebSocket('ws://localhost:3100');

ws.onopen = () => {
  console.log('Connected to OrcBot gateway');
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data);
};

Events

status - Initial agent status after connection:

{
  "type": "status",
  "data": {
    "running": true,
    "model": "gpt-4o",
    "memory": { "short": 45 }
  }
}

event - Agent lifecycle events:

{
  "type": "event",
  "event": "thinking",
  "data": {
    "thought": "I should search for Bitcoin price first"
  }
}

action - Skill execution:

{
  "type": "event",
  "event": "action",
  "data": {
    "skill": "web_search",
    "parameters": { "query": "bitcoin price" }
  }
}

observation - Skill results:

{
  "type": "event",
  "event": "observation",
  "data": {
    "result": "Bitcoin is currently $65,432"
  }
}

Client Actions

Send commands to the gateway via WebSocket: pushTask:

{
  "action": "pushTask",
  "data": {
    "task": "Check server health",
    "priority": 9
  }
}

executeSkill:

{
  "action": "executeSkill",
  "data": {
    "skill": "run_command",
    "parameters": {
      "command": "uptime"
    }
  }
}

getStatus:

{
  "action": "getStatus"
}

setConfig:

{
  "action": "setConfig",
  "data": {
    "key": "modelName",
    "value": "gpt-4o-mini"
  }
}

Authentication

When --api-key is set or gatewayApiKey is configured, all requests require authentication.

REST API

Include X-Api-Key header:

curl -H "X-Api-Key: mysecretkey" http://localhost:3100/api/status

WebSocket

Send API key in connection query string:

const ws = new WebSocket('ws://localhost:3100?apiKey=mysecretkey');

Unauthorized response (401):

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

Background Mode

Run gateway as a background process:

orcbot gateway --background -p 3100 -k mykey

Output:

✅ OrcBot Gateway is running in the background.
   Port: 3100
   Log file: /home/user/.orcbot/gateway.log
   Stop with: pkill -f "orcbot gateway --background-child"

View logs:

tail -f ~/.orcbot/gateway.log

Examples

Basic Gateway

orcbot gateway

Output:

🌐 Starting OrcBot Web Gateway...

📡 Gateway is ready!
   REST API: http://0.0.0.0:3100/api
   WebSocket: ws://0.0.0.0:3100
   Auth: API key required (X-Api-Key header)

   API Endpoints:
   GET  /api/status         - Agent status
   GET  /api/skills         - List skills
   POST /api/tasks          - Push task
   GET  /api/config         - View config
   GET  /api/memory         - View memories
   GET  /api/connections    - Channel status
   GET  /api/logs           - Recent logs

   Press Ctrl+C to stop

💡 Tip: Add --with-agent to also run the agent loop

Gateway with Agent Loop

orcbot gateway --with-agent -k secretkey

Starts both gateway and agent loop in same process. Useful for single-command deployment.

Localhost-Only Gateway

orcbot gateway -h 127.0.0.1 -p 8080

Only accessible from the same machine. More secure for local development.

Gateway with Dashboard

orcbot gateway -s ./apps/dashboard -p 3100

Serves static dashboard files at http://localhost:3100/.

Remote Access with Tailscale

# On server:
orcbot gateway --background -k myapikey

# Get Tailscale IP
tailscale ip -4
# Output: 100.64.0.1

# From remote machine on same Tailnet:
curl -H "X-Api-Key: myapikey" http://100.64.0.1:3100/api/status

Security Best Practices

Never Expose Gateway Publicly Without API KeyIf binding to 0.0.0.0, always set an API key:

orcbot gateway -h 0.0.0.0 -k $(openssl rand -hex 32)

Otherwise, anyone can control your agent remotely.

Recommended: Use Tailscale for Remote AccessInstead of exposing port 3100 to the internet:

Install Tailscale on server and client
Connect both to same Tailnet
Bind gateway to 0.0.0.0 (or Tailscale IP)
Set API key for defense-in-depth
Use Tailnet ACLs to restrict access

Access via Tailscale IP (100.x.x.x) from any authorized device.

HTTPS/TLS

The gateway does not natively support HTTPS. Use a reverse proxy:

server {
    listen 443 ssl;
    server_name orcbot.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://127.0.0.1:3100;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

Configuration

Gateway settings in orcbot.config.yaml:

gatewayPort: 3100
gatewayHost: 0.0.0.0
gatewayApiKey: null  # Set for authentication
gatewayStaticDir: null  # Path to dashboard files
gatewayAutoStart: false  # Auto-start with orcbot run

Troubleshooting

Port Already in Use

# Find process using port
lsof -i :3100

# Kill it
kill <PID>

# Or use different port
orcbot gateway -p 8080

Cannot Connect to WebSocket

# Test with curl
curl http://localhost:3100/api/status

# If REST works but WS doesn't, check firewall
sudo ufw allow 3100

# Test WebSocket with websocat
websocat ws://localhost:3100

401 Unauthorized

# Check if API key is required
curl http://localhost:3100/api/status
# If 401, include key:
curl -H "X-Api-Key: yourkey" http://localhost:3100/api/status

# Or disable API key
orcbot config set gatewayApiKey null
orcbot gateway

Gateway Not Starting with —with-agent

# Check if another instance is running
orcbot status

# Stop existing instance
orcbot stop

# Try again
orcbot gateway --with-agent

orcbot run - Start agent (can auto-start gateway with --with-gateway)
orcbot push - Queue tasks (also available via gateway API)
orcbot ui - TUI management (alternative to gateway)
orcbot stop - Stop all processes including background gateway

​Overview

​Usage

​Options

​REST API Endpoints

​GET /api/status

​GET /api/skills

​POST /api/skills/:name/execute

​POST /api/tasks

​GET /api/tasks

​GET /api/config

​PUT /api/config/:key

​GET /api/memory

​GET /api/connections

​GET /api/logs

​GET /api/security

​PUT /api/security

​WebSocket Interface

​Connection

​Events

​Client Actions

​Authentication

​REST API

​WebSocket

​Background Mode

​Examples

​Basic Gateway

​Gateway with Agent Loop

​Localhost-Only Gateway

​Gateway with Dashboard

​Remote Access with Tailscale

​Security Best Practices

​HTTPS/TLS

​Configuration

​Troubleshooting

​Port Already in Use

​Cannot Connect to WebSocket

​401 Unauthorized

​Gateway Not Starting with —with-agent

​Related Commands

​See Also

Overview

Usage

Options

REST API Endpoints

GET /api/status

GET /api/skills

POST /api/skills/:name/execute

POST /api/tasks

GET /api/tasks

GET /api/config

PUT /api/config/:key

GET /api/memory

GET /api/connections

GET /api/logs

GET /api/security

PUT /api/security

WebSocket Interface

Connection

Events

Client Actions

Authentication

REST API

WebSocket

Background Mode

Examples

Basic Gateway

Gateway with Agent Loop

Localhost-Only Gateway

Gateway with Dashboard

Remote Access with Tailscale

Security Best Practices

HTTPS/TLS

Configuration

Troubleshooting

Port Already in Use

Cannot Connect to WebSocket

401 Unauthorized

Gateway Not Starting with —with-agent

Related Commands

See Also