Deployment - OrcBot

Overview

OrcBot is designed to run as a long-running service that listens for events from Telegram, WhatsApp, Discord, or other channels. This guide covers deployment strategies for production environments.

OrcBot needs to stay active to:

Listen for incoming messages on communication channels
Run scheduled tasks and heartbeats
Process background actions from the queue
Maintain active connections to channel APIs

Deployment Options

1. Daemon Mode (Recommended for VPS)

Best for: Single-server deployments, personal use, development.

# Start as background daemon
orcbot run --daemon

# Check status
orcbot daemon status

# View logs
tail -f ~/.orcbot/daemon.log

# Stop daemon
orcbot daemon stop

Features:

Built-in process management
PID file tracking (~/.orcbot/orcbot.pid)
Log rotation
Graceful shutdown
Conflict detection (prevents multiple instances)

2. Docker (Recommended for Production)

Best for: Cloud deployments, scalability, isolation.

Using Docker Compose (Minimal)

# docker-compose.minimal.yml
version: '3.8'

services:
  orcbot:
    build: .
    image: orcbot:latest
    container_name: orcbot
    restart: unless-stopped
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - TELEGRAM_TOKEN=${TELEGRAM_TOKEN}
    volumes:
      - ./data:/root/.orcbot
    ports:
      - "3100:3100"  # Web gateway (optional)

Setup:

Create .env file

cp .env.example .env
# Edit .env with your API keys

Build and start

docker compose -f docker-compose.minimal.yml up -d

View logs

docker logs -f orcbot

Access shell

docker exec -it orcbot /bin/sh

Using Docker Compose (Full Stack)

# docker-compose.yml
version: '3.8'

services:
  orcbot:
    build:
      context: .
      dockerfile: Dockerfile
    image: orcbot:latest
    container_name: orcbot
    restart: unless-stopped
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - GOOGLE_API_KEY=${GOOGLE_API_KEY}
      - TELEGRAM_TOKEN=${TELEGRAM_TOKEN}
      - WHATSAPP_ENABLED=${WHATSAPP_ENABLED}
      - DISCORD_TOKEN=${DISCORD_TOKEN}
    volumes:
      - ./data:/root/.orcbot
      - ./config:/app/config
    ports:
      - "3100:3100"
    networks:
      - orcbot-network
    healthcheck:
      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3100/api/status', (res) => process.exit(res.statusCode === 200 ? 0 : 1))"]
      interval: 30s
      timeout: 10s
      retries: 3

networks:
  orcbot-network:
    driver: bridge

Start:

docker compose up -d

3. PM2 Process Manager

Best for: Node.js-optimized deployments, shared hosting.

# Install PM2 globally
npm install -g pm2

# Start OrcBot
pm2 start dist/cli/index.js --name orcbot -- run

# View logs
pm2 logs orcbot

# Restart
pm2 restart orcbot

# Stop
pm2 stop orcbot

# Auto-start on system reboot
pm2 startup
pm2 save

PM2 Ecosystem File:

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'orcbot',
    script: './dist/cli/index.js',
    args: 'run',
    instances: 1,
    autorestart: true,
    watch: false,
    max_memory_restart: '1G',
    env: {
      NODE_ENV: 'production',
      ORCBOT_DATA_DIR: '/var/orcbot'
    },
    error_file: './logs/err.log',
    out_file: './logs/out.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss Z'
  }]
};

Start with ecosystem:

pm2 start ecosystem.config.js

4. Systemd Service (Linux)

Best for: Native Linux integration, system-level management.

# /etc/systemd/system/orcbot.service
[Unit]
Description=OrcBot AI Agent
After=network.target

[Service]
Type=simple
User=orcbot
WorkingDirectory=/home/orcbot/orcbot
ExecStart=/usr/bin/node /home/orcbot/orcbot/dist/cli/index.js run
Restart=always
RestartSec=10
StandardOutput=append:/var/log/orcbot/orcbot.log
StandardError=append:/var/log/orcbot/error.log
Environment="NODE_ENV=production"
Environment="ORCBOT_DATA_DIR=/var/lib/orcbot"

[Install]
WantedBy=multi-user.target

Setup:

Create service user

sudo useradd -r -s /bin/false orcbot
sudo mkdir -p /var/lib/orcbot /var/log/orcbot
sudo chown orcbot:orcbot /var/lib/orcbot /var/log/orcbot

Install service file

sudo cp orcbot.service /etc/systemd/system/
sudo systemctl daemon-reload

Enable and start

sudo systemctl enable orcbot
sudo systemctl start orcbot

Check status

sudo systemctl status orcbot
sudo journalctl -u orcbot -f

Cloud Platforms

Railway

Connect repository

Link your GitHub repository to Railway.

Set environment variables

Add OPENAI_API_KEY, TELEGRAM_TOKEN, etc. in the Railway dashboard.

Deploy

Railway auto-detects Node.js and runs npm start.

Procfile:

web: node dist/cli/index.js run

Heroku

# Install Heroku CLI
curl https://cli-assets.heroku.com/install.sh | sh

# Login
heroku login

# Create app
heroku create orcbot-prod

# Set environment variables
heroku config:set OPENAI_API_KEY=sk-...
heroku config:set TELEGRAM_TOKEN=123...

# Deploy
git push heroku main

# View logs
heroku logs --tail

AWS EC2

Launch EC2 instance

AMI: Ubuntu Server 22.04 LTS
Instance type: t3.small (2 vCPU, 2 GB RAM)
Storage: 20 GB SSD

Install dependencies

sudo apt update
sudo apt install -y nodejs npm

Clone and build

git clone https://github.com/fredabila/orcbot.git
cd orcbot
npm install
npm run build

Configure environment

cp .env.example .env
nano .env  # Add your API keys

Start with PM2

npm install -g pm2
pm2 start dist/cli/index.js --name orcbot -- run
pm2 startup
pm2 save

DigitalOcean Droplet

Similar to AWS EC2 - follow the same steps. Recommended: Use Docker for easier deployment.

Configuration for Production

Environment Variables

# .env
NODE_ENV=production
ORCBOT_DATA_DIR=/var/lib/orcbot

# LLM API Keys
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=...

# Channels
TELEGRAM_TOKEN=123...
DISCORD_TOKEN=...
WHATSAPP_ENABLED=true

# Web Gateway
GATEWAY_PORT=3100
GATEWAY_API_KEY=strong-random-key

# Security
SAFE_MODE=false
ADMIN_USER_TELEGRAM=123456789

Production Config

# orcbot.config.yaml
modelName: gpt-4o
llmProvider: openai

# Performance
maxStepsPerAction: 15
maxMessagesPerAction: 25
messageDedupWindow: 5

# Autonomy
autonomyEnabled: true
autonomyInterval: 600000  # 10 minutes
autonomyAllowedChannels:
  - telegram

# Memory
memoryContextLimit: 15000
consolidateThreshold: 100

# Logging
logLevel: info  # info, warn, error (not debug in prod)

# Gateway
gatewayPort: 3100
gatewayHost: 0.0.0.0
gatewayApiKey: ${GATEWAY_API_KEY}

# Security
safeMode: false
adminUsers:
  telegram: ["${ADMIN_USER_TELEGRAM}"]

Monitoring

Health Checks

HTTP Endpoint:

curl http://localhost:3100/api/status

Response:

{
  "status": "running",
  "uptime": 3600,
  "memory": {
    "used": 250,
    "total": 512
  },
  "queueDepth": 0,
  "activeWorkers": 2
}

Docker Healthcheck:

HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3100/api/status', (res) => process.exit(res.statusCode === 200 ? 0 : 1))"

Logging

View Logs:

# Daemon mode
tail -f ~/.orcbot/daemon.log

# Docker
docker logs -f orcbot

# PM2
pm2 logs orcbot

# Systemd
sudo journalctl -u orcbot -f

Log Rotation:

# /etc/logrotate.d/orcbot
/var/log/orcbot/*.log {
    daily
    rotate 14
    compress
    delaycompress
    notifempty
    missingok
    create 0640 orcbot orcbot
}

Metrics

Custom Prometheus Exporter:

// src/utils/metrics.ts
import { Registry, Counter, Gauge } from 'prom-client';

const register = new Registry();

export const tasksProcessed = new Counter({
  name: 'orcbot_tasks_processed_total',
  help: 'Total tasks processed',
  registers: [register]
});

export const queueDepth = new Gauge({
  name: 'orcbot_queue_depth',
  help: 'Current action queue depth',
  registers: [register]
});

export { register };

Expose Metrics:

// In gateway/index.ts
app.get('/metrics', (req, res) => {
  res.set('Content-Type', register.contentType);
  res.end(register.metrics());
});

Updates and Maintenance

Updating OrcBot

Backup data

tar -czf orcbot-backup-$(date +%Y%m%d).tar.gz ~/.orcbot/

Pull updates

cd ~/orcbot
git pull origin main

Install dependencies

npm install

Rebuild

npm run build

Restart

# Daemon
orcbot daemon restart

# Docker
docker compose restart

# PM2
pm2 restart orcbot

# Systemd
sudo systemctl restart orcbot

Database Migrations

OrcBot uses file-based storage by default (no migrations needed). If using SQLite:

# Backup database
cp ~/.orcbot/orcbot.db ~/.orcbot/orcbot.db.backup

# Run migrations (if added in future versions)
node dist/migrations/migrate.js

Troubleshooting

Agent Not Starting

Check logs:

# Daemon
cat ~/.orcbot/daemon.log

# Docker
docker logs orcbot

# Systemd
sudo journalctl -u orcbot -n 50

Common issues:

Missing API keys
Port already in use (3100)
Invalid configuration syntax
Insufficient permissions

High Memory Usage

Symptoms: Agent uses over 1GB RAM. Solutions:

# Reduce memory limits
memoryContextLimit: 10000  # Down from 15000
consolidateThreshold: 50   # More frequent consolidation

# Disable vector memory if not needed
vectorMemoryEnabled: false

Restart periodically:

# With PM2
pm2 start dist/cli/index.js --name orcbot --max-memory-restart 1G -- run

Channel Disconnections

Telegram: Token revoked or bot blocked.

# Test token
curl "https://api.telegram.org/bot<TOKEN>/getMe"

WhatsApp: Session expired.

# Re-pair device
orcbot ui
# Navigate to Connections → WhatsApp → Reconnect

Discord: Invalid token or missing permissions.

# Regenerate token in Discord Developer Portal
# Update config and restart

Best Practices

Use Docker

Containerize for portability and isolation.

Enable Health Checks

Monitor agent status and restart on failure.

Rotate Logs

Prevent disk space issues with log rotation.

Backup Regularly

Backup config and memory daily.

Monitor Resources

Track CPU, memory, and disk usage.

Update Dependencies

Keep Node.js and npm packages up to date.

Configuration

Configure OrcBot for production

Security

Production security best practices

Web Gateway

Expose OrcBot via REST API

Multi-Agent

Scale with worker processes

Get Started

Core Concepts

Guides

Advanced

Documentation Index

​Overview

​Deployment Options

​1. Daemon Mode (Recommended for VPS)

​2. Docker (Recommended for Production)

​Using Docker Compose (Minimal)

​Using Docker Compose (Full Stack)

​3. PM2 Process Manager

​4. Systemd Service (Linux)

​Cloud Platforms

​Railway

​Heroku

​AWS EC2

​DigitalOcean Droplet

​Configuration for Production

​Environment Variables

​Production Config

​Monitoring

​Health Checks

​Logging

​Metrics

​Updates and Maintenance

​Updating OrcBot

​Database Migrations

​Troubleshooting

​Agent Not Starting

​High Memory Usage

​Channel Disconnections

​Best Practices

Use Docker

Enable Health Checks

Rotate Logs

Backup Regularly

Monitor Resources

Update Dependencies

​Related Guides

Configuration

Security

Web Gateway

Multi-Agent

Overview

Deployment Options

1. Daemon Mode (Recommended for VPS)

2. Docker (Recommended for Production)

Using Docker Compose (Minimal)

Using Docker Compose (Full Stack)

3. PM2 Process Manager

4. Systemd Service (Linux)

Cloud Platforms

Railway

Heroku

AWS EC2

DigitalOcean Droplet

Configuration for Production

Environment Variables

Production Config

Monitoring

Health Checks

Logging

Metrics

Updates and Maintenance

Updating OrcBot

Database Migrations

Troubleshooting

Agent Not Starting

High Memory Usage

Channel Disconnections

Best Practices

Related Guides