> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcbot.buzzchat.site/llms.txt
> Use this file to discover all available pages before exploring further.

# orcbot gateway

> Start the OrcBot web gateway server for REST API and WebSocket remote management

## 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

```bash theme={null}
# 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

<ParamField path="-p, --port" type="number" default="3100">
  Port to listen on. Must be available and not used by another process.
</ParamField>

<ParamField path="-h, --host" type="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.
</ParamField>

<ParamField path="-k, --api-key" type="string">
  API key for authentication. If set, all API requests must include `X-Api-Key` header. Overrides `gatewayApiKey` config value.
</ParamField>

<ParamField path="-s, --static" type="string">
  Path to static files for web dashboard. Serves files at root `/`. Useful for hosting a custom frontend.
</ParamField>

<ParamField path="--with-agent" type="boolean" default="false">
  Also start the agent autonomous loop alongside the gateway. Allows full remote operation without separate `orcbot run` command.
</ParamField>

<ParamField path="-b, --background" type="boolean" default="false">
  Run gateway in background (detached process). Logs to `~/.orcbot/gateway.log`. Stop with `pkill -f "orcbot gateway --background-child"`.
</ParamField>

## REST API Endpoints

All endpoints are prefixed with `/api`.

### GET /api/status

Returns agent status and system information.

**Response:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "parameters": {
    "query": "latest AI news",
    "maxResults": 5
  }
}
```

**Response:**

```json theme={null}
{
  "success": true,
  "result": "Search results...",
  "executionTime": 1234
}
```

### POST /api/tasks

Push a new task to the action queue.

**Request:**

```json theme={null}
{
  "task": "Check Bitcoin price and save to journal",
  "priority": 8
}
```

**Response:**

```json theme={null}
{
  "success": true,
  "taskId": "act_1709548815123_abc123",
  "message": "Task queued with priority 8"
}
```

### GET /api/tasks

View current task queue.

**Response:**

```json theme={null}
{
  "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:**

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

### PUT /api/config/:key

Update a configuration value.

**Request:**

```json theme={null}
{
  "value": "gpt-4o-mini"
}
```

**Response:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "safeMode": false,
  "apiKeySet": true,
  "adminUsers": ["user123"],
  "pluginAllowList": [],
  "pluginDenyList": []
}
```

### PUT /api/security

Update security settings.

**Request:**

```json theme={null}
{
  "safeMode": true
}
```

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Security settings updated"
}
```

## WebSocket Interface

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

### Connection

```javascript theme={null}
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:

```json theme={null}
{
  "type": "status",
  "data": {
    "running": true,
    "model": "gpt-4o",
    "memory": { "short": 45 }
  }
}
```

**event** - Agent lifecycle events:

```json theme={null}
{
  "type": "event",
  "event": "thinking",
  "data": {
    "thought": "I should search for Bitcoin price first"
  }
}
```

**action** - Skill execution:

```json theme={null}
{
  "type": "event",
  "event": "action",
  "data": {
    "skill": "web_search",
    "parameters": { "query": "bitcoin price" }
  }
}
```

**observation** - Skill results:

```json theme={null}
{
  "type": "event",
  "event": "observation",
  "data": {
    "result": "Bitcoin is currently $65,432"
  }
}
```

### Client Actions

Send commands to the gateway via WebSocket:

**pushTask**:

```json theme={null}
{
  "action": "pushTask",
  "data": {
    "task": "Check server health",
    "priority": 9
  }
}
```

**executeSkill**:

```json theme={null}
{
  "action": "executeSkill",
  "data": {
    "skill": "run_command",
    "parameters": {
      "command": "uptime"
    }
  }
}
```

**getStatus**:

```json theme={null}
{
  "action": "getStatus"
}
```

**setConfig**:

```json theme={null}
{
  "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:

```bash theme={null}
curl -H "X-Api-Key: mysecretkey" http://localhost:3100/api/status
```

### WebSocket

Send API key in connection query string:

```javascript theme={null}
const ws = new WebSocket('ws://localhost:3100?apiKey=mysecretkey');
```

**Unauthorized response (401):**

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
```

## Background Mode

Run gateway as a background process:

```bash theme={null}
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:**

```bash theme={null}
tail -f ~/.orcbot/gateway.log
```

## Examples

### Basic Gateway

```bash theme={null}
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

```bash theme={null}
orcbot gateway --with-agent -k secretkey
```

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

### Localhost-Only Gateway

```bash theme={null}
orcbot gateway -h 127.0.0.1 -p 8080
```

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

### Gateway with Dashboard

```bash theme={null}
orcbot gateway -s ./apps/dashboard -p 3100
```

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

### Remote Access with Tailscale

```bash theme={null}
# 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

<Warning>
  **Never Expose Gateway Publicly Without API Key**

  If binding to `0.0.0.0`, always set an API key:

  ```bash theme={null}
  orcbot gateway -h 0.0.0.0 -k $(openssl rand -hex 32)
  ```

  Otherwise, anyone can control your agent remotely.
</Warning>

<Note>
  **Recommended: Use Tailscale for Remote Access**

  Instead of exposing port 3100 to the internet:

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

  Access via Tailscale IP (100.x.x.x) from any authorized device.
</Note>

### HTTPS/TLS

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

```nginx theme={null}
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`:

```yaml theme={null}
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

```bash theme={null}
# Find process using port
lsof -i :3100

# Kill it
kill <PID>

# Or use different port
orcbot gateway -p 8080
```

### Cannot Connect to WebSocket

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# Check if another instance is running
orcbot status

# Stop existing instance
orcbot stop

# Try again
orcbot gateway --with-agent
```

## Related Commands

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

## See Also

* [Gateway Server Implementation](https://github.com/fredabila/orcbot) - Source code
* [WebSocket Client Examples](https://fredabila.github.io/orcbot/docs/) - Integration guides
* [Tailscale Setup Guide](https://tailscale.com/kb/1017/install) - Private networking