> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcbot.buzzchat.site/llms.txt
> Use this file to discover all available pages before exploring further.

# orcbot run

> Start the OrcBot autonomous agent loop with daemon and background modes

## 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

```bash theme={null}
# 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

<ParamField path="-d, --daemon" type="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.
</ParamField>

<ParamField path="-b, --background" type="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.
</ParamField>

<ParamField path="--with-gateway" type="boolean" default="false">
  Also start the web gateway server alongside the agent loop. Overrides the `gatewayAutoStart` config setting to `true`.
</ParamField>

<ParamField path="--no-gateway" type="boolean" default="false">
  Disable gateway auto-start even if `gatewayAutoStart` is set to `true` in config.
</ParamField>

<ParamField path="-s, --gateway-static" type="string">
  Path to static files for the gateway dashboard. Default: `apps/dashboard`. Only used when `--with-gateway` is enabled.
</ParamField>

## 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

```bash theme={null}
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`

```bash theme={null}
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

```bash theme={null}
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:**

```yaml theme={null}
gatewayAutoStart: true
gatewayPort: 3100
gatewayHost: 0.0.0.0
gatewayApiKey: your-secret-key
gatewayStaticDir: ./apps/dashboard
```

**Example with gateway:**

```bash theme={null}
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

```bash theme={null}
orcbot run
# Agent starts in current terminal
# Press Ctrl+C to stop
```

### Daemon with Gateway

```bash theme={null}
orcbot run --daemon --with-gateway
# Daemon starts with web gateway enabled
# Access dashboard at http://localhost:3100
```

### Background with Custom Gateway Static Files

```bash theme={null}
orcbot run --background --with-gateway -s /path/to/dashboard
# Runs in background with custom dashboard
```

### Disable Gateway Despite Config

```bash theme={null}
# Even if gatewayAutoStart: true in config
orcbot run --no-gateway
# Gateway will NOT start
```

## Process Management

### Viewing Logs

```bash theme={null}
# 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

```bash theme={null}
# 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`:

```yaml theme={null}
# 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) |

## Related Commands

* [`orcbot daemon`](/api/cli/daemon) - Manage daemon process
* [`orcbot push`](/api/cli/push) - Queue tasks for the running agent
* [`orcbot ui`](/api/cli/ui) - Interactive TUI dashboard
* [`orcbot gateway`](/api/cli/gateway) - Start web gateway separately
* `orcbot stop` - Stop all OrcBot processes

## Troubleshooting

<Warning>
  **Multiple Instance Error**: If you see "OrcBot is already running" but believe it's a false positive:

  ```bash theme={null}
  # Check for actual running processes
  ps aux | grep orcbot

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

  # Try again
  orcbot run
  ```
</Warning>

<Note>
  **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`
</Note>