orcbot run

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

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.

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.

boolean

default:"false"

Also start the web gateway server alongside the agent loop. Overrides the gatewayAutoStart config setting to true.

boolean

default:"false"

Disable gateway auto-start even if gatewayAutoStart is set to true in config.

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:

Lock File Check: Before starting, checks for ~/.orcbot/orcbot.lock containing PID, start time, and host information
Process Validation: Verifies the process is actually running (not just a stale lock file)
Stale Lock Cleanup: Automatically removes lock files from crashed instances
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:

--with-gateway flag (explicit enable)
--no-gateway flag (explicit disable)
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

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

orcbot daemon - Manage daemon process
orcbot push - Queue tasks for the running agent
orcbot ui - Interactive TUI dashboard
orcbot gateway - Start web gateway separately
orcbot stop - Stop all OrcBot processes

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:

Check config: orcbot config get gatewayPort
Ensure port is available: lsof -i :3100
Check logs for errors: tail -f ~/.orcbot/daemon.log

CLI Commands

Core Skills

Configuration

Overview

Usage

Options

Behavior

Instance Conflict Detection

Foreground Mode

Daemon Mode

Background Mode

Gateway Auto-Start

Examples

Basic Foreground Start

Daemon with Gateway

Background with Custom Gateway Static Files

Disable Gateway Despite Config

Process Management

Viewing Logs

Stopping the Agent

Configuration

Exit Codes

Troubleshooting

​Overview

​Usage

​Options

​Behavior

​Instance Conflict Detection

​Foreground Mode

​Daemon Mode

​Background Mode

​Gateway Auto-Start

​Examples

​Basic Foreground Start

​Daemon with Gateway

​Background with Custom Gateway Static Files

​Disable Gateway Despite Config

​Process Management

​Viewing Logs

​Stopping the Agent

​Configuration

​Exit Codes

​Related Commands

​Troubleshooting

Overview

Usage

Options

Behavior

Instance Conflict Detection

Foreground Mode

Daemon Mode

Background Mode

Gateway Auto-Start

Examples

Basic Foreground Start

Daemon with Gateway

Background with Custom Gateway Static Files

Disable Gateway Despite Config

Process Management

Viewing Logs

Stopping the Agent

Configuration

Exit Codes

Related Commands

Troubleshooting