Installation

System Requirements

OrcBot is a Node.js application that runs on Linux, macOS, and Windows.

Minimum Requirements

Node.js: 18.x or higher
npm: 8.x or higher
RAM: 512 MB minimum, 2 GB recommended
Disk: 500 MB for installation, 2+ GB for operation
Network: Internet connection for LLM API calls

Recommended Setup

Node.js: Latest LTS version (20.x)
RAM: 4 GB or more for browser automation
Disk: SSD with 5+ GB free space
OS: Linux (Ubuntu 22.04+), macOS (12+), or Windows 10+

One-Line Installation

The fastest way to install OrcBot:

Linux / macOS
Windows PowerShell

curl -sSL https://orcbot.ai/install.sh | bash

The installer will:

Check for Node.js and npm
Clone the repository
Install dependencies
Build the project
Add orcbot to your PATH
Run the setup wizard

If you prefer to review the script first: curl -sSL https://orcbot.ai/install.sh > install.sh && bash install.sh

iwr https://orcbot.vercel.app/install.ps1 | iex

The installer will:

Verify Node.js installation
Download the repository
Install dependencies
Compile TypeScript
Configure system PATH
Launch setup wizard

Run PowerShell as Administrator for proper PATH configuration.

Manual Installation

Install Node.js

Download and install Node.js 18+ from nodejs.org.Verify installation:

node --version  # Should be v18.0.0 or higher
npm --version   # Should be 8.0.0 or higher

Ubuntu / Debian
macOS
Windows

# Using NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Using Homebrew
brew install node@20

Download the installer from nodejs.org and run it. Or use Chocolatey:

choco install nodejs-lts

Clone the Repository

git clone https://github.com/fredabila/orcbot.git
cd orcbot

For a specific version: git clone --branch v2.1.0 https://github.com/fredabila/orcbot.git

Install Dependencies

npm install

This installs all required packages including:

TypeScript compiler
Playwright for browser automation
Telegraf for Telegram integration
Discord.js for Discord support
WhatsApp Baileys for WhatsApp
And more…

Installation may take 3-5 minutes depending on your network speed.

Build the Project

Compile TypeScript to JavaScript:

npm run build

Or use the fast build (using esbuild):

npm run build:fast

The compiled output will be in the dist/ directory.

Run Setup Wizard

npm run setup

Or if the binary is built:

./dist/cli/index.js setup

The wizard will configure:

AI model and provider
API keys
Communication channels
Agent identity
Autonomy settings

Make CLI Globally Available (Optional)

npm link
Add to PATH
Alias

npm link

Now you can run orcbot from anywhere.

Add the dist/cli directory to your PATH:

echo 'export PATH="$PATH:/path/to/orcbot/dist/cli"' >> ~/.bashrc
source ~/.bashrc

Create an alias in your shell config:

echo 'alias orcbot="node /path/to/orcbot/dist/cli/index.js"' >> ~/.bashrc
source ~/.bashrc

Docker Installation

Docker deployment is recommended for production servers and consistent environments.

Install Docker

Install Docker and Docker Compose:

Linux
macOS
Windows

# Docker
curl -fsSL https://get.docker.com | sh

# Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" \
  -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Prepare Configuration

Clone the repository and copy the example environment file:

git clone https://github.com/fredabila/orcbot.git
cd orcbot
cp .env.example .env

Edit .env with your API keys and settings:

nano .env  # or use your preferred editor

Required variables:

OPENAI_API_KEY=sk-...
MODEL_NAME=gpt-4o
AGENT_NAME=OrcBot

Choose a Docker Compose File

OrcBot provides multiple Docker configurations:

Minimal
Full
Development

Basic setup with core features:

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

Complete setup with all features:

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

Development mode with hot reload:

docker compose -f docker-compose.dev.yml up

Access the Dashboard

Once running, access the web gateway:

http://localhost:3100

View logs:

docker compose logs -f orcbot

Stop the container:

docker compose down

Docker Management

# Start
docker compose up -d

# Stop
docker compose down

# Restart
docker compose restart

# View logs
docker compose logs -f

# Last 100 lines
docker compose logs --tail=100

# Enter container
docker compose exec orcbot sh

# Run command
docker compose exec orcbot orcbot status

# Pull latest changes
git pull

# Rebuild and restart
docker compose build
docker compose up -d

Platform-Specific Setup

Linux

Ubuntu / Debian
Fedora / RHEL
Arch Linux

# Update system
sudo apt update && sudo apt upgrade -y

# Install dependencies
sudo apt install -y git curl build-essential

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Clone and install OrcBot
git clone https://github.com/fredabila/orcbot.git
cd orcbot
npm install
npm run build
npm run setup

# Install Node.js
sudo dnf install -y nodejs npm git

# Clone and install OrcBot
git clone https://github.com/fredabila/orcbot.git
cd orcbot
npm install
npm run build
npm run setup

# Install Node.js
sudo pacman -S nodejs npm git

# Clone and install OrcBot
git clone https://github.com/fredabila/orcbot.git
cd orcbot
npm install
npm run build
npm run setup

Linux System Service

Create a systemd service for OrcBot:

sudo nano /etc/systemd/system/orcbot.service

Add:

[Unit]
Description=OrcBot Autonomous Agent
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/path/to/orcbot
ExecStart=/usr/bin/node /path/to/orcbot/dist/cli/index.js run --daemon
Restart=on-failure
RestartSec=10
Environment="NODE_ENV=production"
Environment="OPENAI_API_KEY=your-key-here"

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable orcbot
sudo systemctl start orcbot
sudo systemctl status orcbot

macOS

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js
brew install node@20

# Clone repository
git clone https://github.com/fredabila/orcbot.git
cd orcbot

# Install and build
npm install
npm run build
npm run setup

macOS Launch Agent

Create a launch agent to run OrcBot at login:

nano ~/Library/LaunchAgents/com.orcbot.agent.plist

Add:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.orcbot.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/node</string>
        <string>/path/to/orcbot/dist/cli/index.js</string>
        <string>run</string>
        <string>--daemon</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/orcbot.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/orcbot.error.log</string>
</dict>
</plist>

Load the agent:

launchctl load ~/Library/LaunchAgents/com.orcbot.agent.plist

Windows

Install Prerequisites

Using PowerShell (as Administrator):

# Install Chocolatey
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install Node.js and Git
choco install nodejs-lts git -y

Clone and Install

# Clone repository
git clone https://github.com/fredabila/orcbot.git
cd orcbot

# Install dependencies
npm install

# Build
npm run build

# Setup
npm run setup

Run OrcBot

# Start in foreground
node dist/cli/index.js run

# Or start in background
Start-Process -NoNewWindow -FilePath "node" -ArgumentList "dist/cli/index.js", "run", "--daemon"

Windows Service

To run OrcBot as a Windows service, use node-windows:

npm install -g node-windows

Create service.js:

const Service = require('node-windows').Service;

const svc = new Service({
  name: 'OrcBot',
  description: 'OrcBot Autonomous Agent',
  script: 'C:\\path\\to\\orcbot\\dist\\cli\\index.js',
  scriptOptions: 'run --daemon',
  nodeOptions: ['--harmony', '--max_old_space_size=4096']
});

svc.on('install', () => {
  svc.start();
});

svc.install();

Install:

node service.js

Configuration

After installation, configure OrcBot:

Run Setup Wizard

orcbot setup

The wizard configures:

AI Model: Choose OpenAI, Google Gemini, AWS Bedrock, etc.
API Keys: Enter your provider API keys
Channels: Configure Telegram, Discord, WhatsApp
Identity: Set agent name and personality
Autonomy: Enable/disable autonomous operations

Manual Configuration

Configuration files are stored in ~/.orcbot/:

orcbot.config.yaml: Main configuration
.env: Environment variables
AGENTS.md, SOUL.md: Bootstrap files

Edit the config:

nano ~/.orcbot/orcbot.config.yaml

Key settings:

# LLM Configuration
modelName: gpt-4o
llmProvider: openai
openaiApiKey: sk-...

# Channels
telegramToken: "your-bot-token"
discordToken: "your-discord-token"
whatsappEnabled: false

# Autonomy
autonomyEnabled: true
autonomyInterval: 3600

# Web Gateway
gatewayPort: 3100
gatewayApiKey: "your-secret-key"

Environment Variables

Alternatively, use environment variables:

export OPENAI_API_KEY="sk-..."
export MODEL_NAME="gpt-4o"
export TELEGRAM_TOKEN="your-bot-token"
export AGENT_NAME="OrcBot"

Environment variables override config file settings.

Verification

Verify your installation:

Check Version

orcbot --version

Test Configuration

orcbot config get modelName

Run Status Check

orcbot status

Test a Simple Task

orcbot run &
sleep 3
orcbot push "What is 2+2?"

Check Logs

tail -f ~/.orcbot/daemon.log

Optional Components

Lightpanda Browser (Lightweight)

Lightpanda uses 9x less RAM than Chrome:

# Install
orcbot lightpanda install

# Start
orcbot lightpanda start --background

# Enable
orcbot lightpanda enable

Lightpanda is only available on Linux x64 and macOS ARM64. Use WSL2 on Windows.

Ollama (Local LLMs)

Run LLMs locally without API calls:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a model
ollama pull llama2

# Configure OrcBot
orcbot config set modelName ollama/llama2
orcbot config set llmProvider ollama
orcbot config set ollamaEndpoint http://localhost:11434

Troubleshooting

npm install fails

Clear npm cache:

npm cache clean --force
npm install

Or delete node_modules and reinstall:

rm -rf node_modules package-lock.json
npm install

Build errors

Check TypeScript version:

npm list typescript

Reinstall TypeScript:

npm install --save-dev typescript@latest
npm run build

Permission errors (Linux/macOS)

Don’t use sudo with npm. Fix permissions:

sudo chown -R $USER:$USER ~/.npm
sudo chown -R $USER:$USER ~/.orcbot

PATH not updated

Manually add to PATH:

echo 'export PATH="$PATH:$HOME/.orcbot/bin"' >> ~/.bashrc
source ~/.bashrc

Playwright browser installation fails

Install browsers manually:

npx playwright install chromium

Updating OrcBot

Automatic
Manual
Docker

orcbot update

cd /path/to/orcbot
git pull origin main
npm install
npm run build

docker compose pull
docker compose up -d

Uninstallation

This will remove OrcBot and all its data. Make sure to backup important configurations and memory files.

# Stop OrcBot
orcbot stop

# Remove installation directory
rm -rf /path/to/orcbot

# Remove data directory
rm -rf ~/.orcbot

# Remove from PATH (if using npm link)
npm unlink orcbot

Next Steps

Quick Start

Get up and running in 5 minutes

Configuration

Configure OrcBot for your use case

Skills & Plugins

Extend OrcBot with custom skills

API Reference

Complete API documentation

Get Started

Core Concepts

Guides

Advanced

System Requirements

Minimum Requirements

Recommended Setup

One-Line Installation

Manual Installation

Docker Installation

Docker Management

Platform-Specific Setup

Linux

Linux System Service

macOS

macOS Launch Agent

Windows

Windows Service

Configuration

Verification

Optional Components

Lightpanda Browser (Lightweight)

Ollama (Local LLMs)

Troubleshooting

Updating OrcBot

Uninstallation

Next Steps

Quick Start

Configuration

Skills & Plugins

API Reference

​System Requirements

​Minimum Requirements

​Recommended Setup

​One-Line Installation

​Manual Installation

​Docker Installation

​Docker Management

​Platform-Specific Setup

​Linux

​Linux System Service

​macOS

​macOS Launch Agent

​Windows

​Windows Service

​Configuration

​Verification

​Optional Components

​Lightpanda Browser (Lightweight)

​Ollama (Local LLMs)

​Troubleshooting

​Updating OrcBot

​Uninstallation

​Next Steps

Quick Start

Configuration

Skills & Plugins

API Reference

System Requirements

Minimum Requirements

Recommended Setup

One-Line Installation

Manual Installation

Docker Installation

Docker Management

Platform-Specific Setup

Linux

Linux System Service

macOS

macOS Launch Agent

Windows

Windows Service

Configuration

Verification

Optional Components

Lightpanda Browser (Lightweight)

Ollama (Local LLMs)

Troubleshooting

Updating OrcBot

Uninstallation

Next Steps