Quick Start

Prerequisites

Before you begin, ensure you have:

Node.js 18+ installed
An OpenAI API key or other supported LLM provider
Terminal access (Linux, macOS, or Windows with PowerShell)

OrcBot requires API keys for LLM providers. Have your OpenAI, Google Gemini, or other API key ready.

Installation

Install with one command

Choose your platform:

Linux / macOS
Windows PowerShell
Docker
Manual

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

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

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

# Copy and edit environment variables
cp .env.example .env

# Start with Docker Compose
docker compose -f docker-compose.minimal.yml up -d

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

# Install dependencies
npm install

# Build the project
npm run build

# Run setup wizard
npm run setup

Run the setup wizard

Launch the interactive configuration:

orcbot setup

The wizard will guide you through:

Setting your AI model (OpenAI, Google Gemini, etc.)
Configuring API keys
Setting up communication channels (optional)
Choosing autonomy settings

For a minimal setup, you only need an OpenAI API key. Other channels can be configured later.

Start OrcBot

Launch the agent loop:

orcbot run

# Run in the current terminal (Ctrl+C to stop)
orcbot run

# Run as background service
orcbot run --daemon

# Check status
orcbot daemon status

# Stop daemon
orcbot daemon stop

# Start agent loop + REST API server
orcbot run --with-gateway

# Dashboard available at http://localhost:3100

OrcBot includes conflict detection. Only one instance can run at a time to prevent duplicate operations.

Your First Task

Push a manual task

While OrcBot is running, open a new terminal and push a task:

orcbot push "Search for the latest AI news and summarize the top 3 stories"

You can also specify priority (1-10, default 5):

orcbot push "Deploy the staging branch" --priority 8

Watch the reasoning process

OrcBot will:

SIMULATE: Create a pre-execution plan
THINK: Reason about the task
ACT: Execute skills (web_search, browser_navigate, etc.)
OBSERVE: Process results
FINALIZE: Complete the task

Example output:

[SIMULATE] Planning task: Search for latest AI news...
[THOUGHT] I need to search the web for recent AI news articles
[ACTION] web_search("latest AI news 2024")
[OBSERVATION] Found 10 results from various sources...
[THOUGHT] I should extract the top 3 articles and summarize them
[ACTION] browser_navigate("https://example.com/ai-article")
[OBSERVATION] Retrieved article content...
[FINALIZE] Task completed successfully

Check the results

View recent memory and task status:

orcbot status

This shows:

Running instance status
Action queue state
Memory statistics
Recent activities

Interactive TUI Dashboard

For a visual interface, launch the TUI (Terminal User Interface):

orcbot ui

The TUI provides:

Real-time Dashboard: Agent status, queue, memory stats
Model Management: Configure OpenAI, Gemini, and other providers
Connection Setup: Telegram, WhatsApp, Discord, Slack
Skill Management: Install, activate, and configure skills
Worker Management: Monitor multi-agent orchestration
Token Usage: View API consumption and costs
Security Settings: Configure admin permissions and safe mode

Common Commands

# Foreground
orcbot run

# Background daemon
orcbot run --daemon

# With web gateway
orcbot run --with-gateway

# Push a task
orcbot push "Your task here" --priority 5

# View status
orcbot status

# Open TUI
orcbot ui

# Run setup wizard
orcbot setup

# Get config value
orcbot config get modelName

# Set config value
orcbot config set modelName gpt-4o

# List installed skills
orcbot skill list

# Install a skill
orcbot skill install <github-url>

# Create new skill
orcbot skill create my-skill

# Stop all instances
orcbot stop

# Check daemon status
orcbot daemon status

# Update OrcBot
orcbot update

Example Workflows

Daily News Briefing

orcbot push "Search for tech news from the last 24 hours, \
summarize the top 5 stories, and save to my journal" --priority 5

System Monitoring

orcbot push "Check disk usage, CPU load, and memory. \
If any metric exceeds 80%, send me an alert" --priority 8

Code Review Helper

orcbot push "Read the latest commit in the main branch, \
analyze the changes, and write a summary with potential issues" --priority 6

Research Assistant

orcbot push "Research quantum computing breakthroughs in 2024, \
ingest the findings into my knowledge base, and create a summary report" --priority 4

Web Gateway (Optional)

The web gateway provides REST API and WebSocket access:

Start the gateway

orcbot gateway --port 3100 --api-key your-secret-key

Or start with the agent loop:

orcbot run --with-gateway

Test the API

# Check agent status
curl -H "X-Api-Key: your-secret-key" \
  http://localhost:3100/api/status

# Push a task
curl -X POST \
  -H "X-Api-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"task": "Hello from API", "priority": 5}' \
  http://localhost:3100/api/tasks

Connect via WebSocket

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

ws.on('open', () => {
  ws.send(JSON.stringify({
    action: 'pushTask',
    data: { task: 'Test task', priority: 5 }
  }));
});

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

For remote access, use Tailscale or another VPN instead of exposing the gateway port publicly. Always set an API key.

Setting Up Communication Channels

Telegram
Discord
WhatsApp

Create a bot with @BotFather
Get your bot token

Configure OrcBot:

orcbot config set telegramToken "your-bot-token"

Restart OrcBot
Start a chat with your bot on Telegram

Create a Discord application at Discord Developer Portal
Create a bot and get the token

Configure OrcBot:

orcbot config set discordToken "your-bot-token"

Invite the bot to your server
Restart OrcBot

Enable WhatsApp:
orcbot config set whatsappEnabled true
Start OrcBot - a QR code will appear
Scan the QR code with WhatsApp (Settings > Linked Devices)
Session is saved for future runs

Next Steps

Installation Guide

Detailed setup instructions for all platforms

Configuration

Learn about all configuration options

Skills System

Extend OrcBot with custom skills

API Reference

Complete API documentation

Troubleshooting

OrcBot won't start

Check for existing instances:

orcbot status

If a stale instance is detected:

orcbot stop

Then try starting again:

orcbot run

API key errors

Verify your API key is set:

orcbot config get openaiApiKey

Set it if missing:

orcbot config set openaiApiKey "sk-..."

Or use environment variables:

export OPENAI_API_KEY="sk-..."

Port conflicts

If the gateway port is in use:

orcbot gateway --port 3200

Or set it in config:

orcbot config set gatewayPort 3200

Memory issues

Reset memory if corrupted:

orcbot reset --memory

View memory stats:

orcbot status

Getting Help

GitHub Issues: Report bugs or request features
Documentation: Full documentation
Discord Community: Join the OrcBot Discord server

Run orcbot --help or orcbot <command> --help for detailed command information.

Get Started

Core Concepts

Guides

Advanced

Prerequisites

Installation

Your First Task

Interactive TUI Dashboard

Common Commands

Example Workflows

Daily News Briefing

System Monitoring

Code Review Helper

Research Assistant

Web Gateway (Optional)

Setting Up Communication Channels

Next Steps

Installation Guide

Configuration

Skills System

API Reference

Troubleshooting

Getting Help

​Prerequisites

​Installation

​Your First Task

​Interactive TUI Dashboard

​Common Commands

​Example Workflows

​Daily News Briefing

​System Monitoring

​Code Review Helper

​Research Assistant

​Web Gateway (Optional)

​Setting Up Communication Channels

​Next Steps

Installation Guide

Configuration

Skills System

API Reference

​Troubleshooting

​Getting Help

Prerequisites

Installation

Your First Task

Interactive TUI Dashboard

Common Commands

Example Workflows

Daily News Briefing

System Monitoring

Code Review Helper

Research Assistant

Web Gateway (Optional)

Setting Up Communication Channels

Next Steps

Troubleshooting

Getting Help