Skip to main content

​
Overview

The orcbot run command starts the OrcBot autonomous reasoning loop. It supports foreground mode, daemon mode (detached background process), and background mode (nohup-style), with built-in conflict detection to prevent multiple instances.

​
Usage

# Start in foreground mode (blocks terminal)
orcbot run

# Start as daemon (detached background process)
orcbot run --daemon

# Start in background (nohup-style)
orcbot run --background

# Start with web gateway enabled
orcbot run --with-gateway

# Start with custom static files for gateway dashboard
orcbot run --with-gateway -s ./apps/dashboard

​
Options

​
-d, --daemon
boolean
default:"false"
Run in background as a daemon process. Creates PID file at ~/.orcbot/orcbot.pid and logs to ~/.orcbot/daemon.log. Process is fully detached from the terminal.
​
-b, --background
boolean
default:"false"
Run in background using nohup-style process spawning. Logs to ~/.orcbot/foreground.log. Unlike daemon mode, this uses a different spawning strategy.
​
--with-gateway
boolean
default:"false"
Also start the web gateway server alongside the agent loop. Overrides the gatewayAutoStart config setting to true.
​
--no-gateway
boolean
default:"false"
Disable gateway auto-start even if gatewayAutoStart is set to true in config.
​
-s, --gateway-static
string
Path to static files for the gateway dashboard. Default: apps/dashboard. Only used when --with-gateway is enabled.

​
Behavior

​
Instance Conflict Detection

OrcBot implements robust conflict detection to prevent multiple agent instances from running simultaneously:
  1. Lock File Check: Before starting, checks for ~/.orcbot/orcbot.lock containing PID, start time, and host information
  2. Process Validation: Verifies the process is actually running (not just a stale lock file)
  3. Stale Lock Cleanup: Automatically removes lock files from crashed instances
  4. Clear Error Messages: Provides PID, start time, and instructions when instance already exists
If an instance is already running: 
❌ OrcBot is already running!
   PID: 12345
   Started: 2026-03-04T10:30:15.000Z
   Host: myserver

   To check what's running:
   $ ps aux | grep orcbot

   To stop ALL OrcBot processes:
   $ pkill -f "orcbot"  OR  systemctl stop orcbot

   Then try again.

​
Foreground Mode

When run without flags:
  • Agent loop runs in the current terminal
  • Press Ctrl+C to stop
  • Logs to stdout/stderr
  • Also checks for existing daemon and prevents startup if daemon is running
orcbot run
# Output:
# Agent loop starting... (Press Ctrl+C to stop)

​
Daemon Mode

When run with --daemon:
  • Process detaches from terminal
  • Continues running after terminal closes
  • PID written to ~/.orcbot/orcbot.pid
  • Logs redirected to ~/.orcbot/daemon.log
  • Manage with orcbot daemon status/stop
orcbot run --daemon
# Process detaches immediately

# Check status
orcbot daemon status

# Stop daemon
orcbot daemon stop

​
Background Mode

When run with --background:
  • Spawns a detached child process
  • Logs to ~/.orcbot/foreground.log
  • Stop with orcbot stop command
orcbot run --background
# Output:
# ✅ OrcBot is running in the background.
#    Log file: /home/user/.orcbot/foreground.log
#    Stop with: orcbot stop

​
Gateway Auto-Start

The agent can optionally start the web gateway server when launched: Priority order:
  1. --with-gateway flag (explicit enable)
  2. --no-gateway flag (explicit disable)
  3. gatewayAutoStart config value
Configuration: 
gatewayAutoStart: true
gatewayPort: 3100
gatewayHost: 0.0.0.0
gatewayApiKey: your-secret-key
gatewayStaticDir: ./apps/dashboard
Example with gateway: 
orcbot run --with-gateway
# Output:
# Agent loop starting... (Press Ctrl+C to stop)
# 🌐 Gateway server listening on http://0.0.0.0:3100

​
Examples

​
Basic Foreground Start

orcbot run
# Agent starts in current terminal
# Press Ctrl+C to stop

​
Daemon with Gateway

orcbot run --daemon --with-gateway
# Daemon starts with web gateway enabled
# Access dashboard at http://localhost:3100

​
Background with Custom Gateway Static Files

orcbot run --background --with-gateway -s /path/to/dashboard
# Runs in background with custom dashboard

​
Disable Gateway Despite Config

# Even if gatewayAutoStart: true in config
orcbot run --no-gateway
# Gateway will NOT start

​
Process Management

​
Viewing Logs

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

# Background logs
tail -f ~/.orcbot/foreground.log

# Via gateway API
curl http://localhost:3100/api/logs

​
Stopping the Agent

# Stop daemon specifically
orcbot daemon stop

# Stop ALL OrcBot processes (daemon, background, gateway)
orcbot stop

# Force kill if graceful shutdown fails
orcbot stop --force

​
Configuration

Key config values that affect orcbot run: 
# Gateway auto-start
gatewayAutoStart: false
gatewayPort: 3100
gatewayHost: 0.0.0.0
gatewayApiKey: null
gatewayStaticDir: null

# Agent behavior
autonomyEnabled: true
autonomyInterval: 1800000  # 30 minutes
maxStepsPerAction: 20
maxMessagesPerAction: 30

​
Exit Codes

CodeMeaning
0Clean shutdown
1Another instance already running
1Daemon already running (when starting in foreground)

​
Troubleshooting

Multiple Instance Error: If you see “OrcBot is already running” but believe it’s a false positive:
# Check for actual running processes
ps aux | grep orcbot

# If none found, manually remove stale lock
rm ~/.orcbot/orcbot.lock

# Try again
orcbot run
Gateway Not Starting: If --with-gateway doesn’t start the gateway:
  1. Check config: orcbot config get gatewayPort
  2. Ensure port is available: lsof -i :3100
  3. Check logs for errors: tail -f ~/.orcbot/daemon.log