Skip to main content

​
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

1

Install with one command

Choose your platform:
curl -sSL https://orcbot.ai/install.sh | bash
2

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.
3

Start OrcBot

Launch the agent loop:
orcbot run

# Run in the current terminal (Ctrl+C to stop)
orcbot run
OrcBot includes conflict detection. Only one instance can run at a time to prevent duplicate operations.

​
Your First Task

1

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
2

Watch the reasoning process

OrcBot will:
  1. SIMULATE: Create a pre-execution plan
  2. THINK: Reason about the task
  3. ACT: Execute skills (web_search, browser_navigate, etc.)
  4. OBSERVE: Process results
  5. 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
3

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
OrcBot TUI Dashboard
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

​
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:
1

Start the gateway

orcbot gateway --port 3100 --api-key your-secret-key
Or start with the agent loop:
orcbot run --with-gateway
2

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
3

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

  1. Create a bot with @BotFather
  2. Get your bot token
  3. Configure OrcBot: 
    orcbot config set telegramToken "your-bot-token"
  4. Restart OrcBot
  5. Start a chat with your bot on Telegram

​
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

Check for existing instances:
orcbot status
If a stale instance is detected:
orcbot stop
Then try starting again:
orcbot run
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-..."
If the gateway port is in use:
orcbot gateway --port 3200
Or set it in config:
orcbot config set gatewayPort 3200
Reset memory if corrupted:
orcbot reset --memory
View memory stats:
orcbot status

​
Getting Help

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