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

> Manage the OrcBot daemon process with status checks and graceful shutdown

## Overview

The `orcbot daemon` command manages the OrcBot background daemon process. It provides status checks and graceful shutdown capabilities for daemon instances started with `orcbot run --daemon`.

## Usage

```bash theme={null}
# Check daemon status (default action)
orcbot daemon
orcbot daemon status

# Stop the daemon
orcbot daemon stop

# Start daemon (alias for orcbot run --daemon)
orcbot daemon start

# Restart daemon
orcbot daemon restart
```

## Subcommands

### status

Check if the OrcBot daemon is running and display its status.

```bash theme={null}
orcbot daemon status
```

**Output when running:**

```
🟢 OrcBot Daemon is RUNNING
   PID: 12345
   Started: 2026-03-04T10:30:15.000Z
   Log: /home/user/.orcbot/daemon.log
```

**Output when stopped:**

```
🔴 OrcBot Daemon is NOT running
   To start: orcbot run --daemon
```

**Stale PID handling:**
If a PID file exists but the process is not running, the status command automatically cleans up the stale file:

```
🔴 OrcBot Daemon is NOT running
   🧹 Cleaned up stale PID file
```

### stop

Gracefully stop the running daemon by sending SIGTERM.

```bash theme={null}
orcbot daemon stop
```

**Output:**

```
✅ Sent stop signal to daemon (PID: 12345)
   Use "orcbot daemon status" to verify it stopped
   Or use "orcbot stop" to stop all OrcBot processes
```

**If daemon is not running:**

```
OrcBot daemon is not running
```

### start

Start the daemon (equivalent to `orcbot run --daemon`).

```bash theme={null}
orcbot daemon start
```

This is an alias that:

1. Calls `daemonManager.daemonize()` to detach the process
2. Redirects logs to `~/.orcbot/daemon.log`
3. Writes PID to `~/.orcbot/orcbot.pid`
4. Starts the agent loop

### restart

Stop the current daemon (if running) and start a new one.

```bash theme={null}
orcbot daemon restart
```

**Behavior:**

1. If daemon is running, sends SIGTERM to current PID
2. Waits for graceful shutdown
3. Starts new daemon process
4. Outputs new PID and log location

## Daemon Process Details

### PID File

**Location:** `~/.orcbot/orcbot.pid`

**Contents:** Plain text integer (process ID)

```
12345
```

### Log File

**Location:** `~/.orcbot/daemon.log`

**Format:** Append-only log with timestamps

```
2026-03-04T10:30:15.000Z [info] Agent loop starting in daemon mode...
2026-03-04T10:30:16.123Z [info] Memory loaded: 45 entries
2026-03-04T10:30:17.456Z [info] Action queue: 3 pending tasks
```

**Viewing logs in real-time:**

```bash theme={null}
tail -f ~/.orcbot/daemon.log
```

### Lock File

**Location:** `~/.orcbot/orcbot.lock`

**Contents:** JSON with instance metadata

```json theme={null}
{
  "pid": 12345,
  "startedAt": "2026-03-04T10:30:15.000Z",
  "host": "myserver",
  "cwd": "/home/user/projects/orcbot"
}
```

This lock file prevents multiple instances from running simultaneously.

## Examples

### Start and Monitor Daemon

```bash theme={null}
# Start daemon
orcbot run --daemon

# Check status
orcbot daemon status
# Output: 🟢 OrcBot Daemon is RUNNING (PID: 12345)

# Monitor logs
tail -f ~/.orcbot/daemon.log
```

### Graceful Restart

```bash theme={null}
# Check current status
orcbot daemon status

# Restart daemon
orcbot daemon restart

# Verify new instance
orcbot daemon status
# New PID will be shown
```

### Force Stop Stuck Daemon

```bash theme={null}
# Try graceful stop first
orcbot daemon stop

# If that fails, use force stop
orcbot stop --force

# Verify it stopped
orcbot daemon status
```

### Clean Up After Crash

```bash theme={null}
# If daemon crashed, status will show stale PID
orcbot daemon status
# Output: 🔴 OrcBot Daemon is NOT running
#         🧹 Cleaned up stale PID file

# Restart fresh
orcbot run --daemon
```

## Process Lifecycle

### Starting

1. Check for existing daemon (via PID file)
2. Create `~/.orcbot/orcbot.lock` with instance metadata
3. Fork process and detach from terminal
4. Redirect stdio to `~/.orcbot/daemon.log`
5. Write PID to `~/.orcbot/orcbot.pid`
6. Start agent loop

### Running

1. Agent executes autonomous reasoning loop
2. Processes queued tasks from ActionQueue
3. Handles channel events (Telegram, WhatsApp, etc.)
4. Runs heartbeat tasks on schedule
5. Logs all activity to daemon.log

### Stopping

1. SIGTERM signal sent to daemon process
2. Graceful shutdown initiated:
   * Current action completes
   * Memory flushed to disk
   * Channels disconnected
   * Gateway stopped (if running)
3. PID file removed
4. Lock file removed
5. Process exits

## Integration with Other Commands

### orcbot run

```bash theme={null}
# These are equivalent:
orcbot run --daemon
orcbot daemon start

# Both create daemon process
```

### orcbot stop

```bash theme={null}
# Stops ALL OrcBot processes including daemon
orcbot stop

# More targeted daemon-only stop:
orcbot daemon stop
```

### orcbot status

```bash theme={null}
# General status (includes daemon check)
orcbot status

# Daemon-specific status
orcbot daemon status
```

## Troubleshooting

<Warning>
  **Daemon Won't Start**: If `orcbot run --daemon` fails with "already running" error:

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

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

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

<Warning>
  **Daemon Won't Stop**: If `orcbot daemon stop` doesn't stop the process:

  ```bash theme={null}
  # Check if process exists
  cat ~/.orcbot/orcbot.pid
  ps aux | grep <PID>

  # Force kill
  kill -9 <PID>

  # Or use force stop
  orcbot stop --force

  # Clean up
  rm ~/.orcbot/orcbot.pid
  ```
</Warning>

<Note>
  **Daemon Logs Growing Large**: Daemon logs are append-only and can grow over time:

  ```bash theme={null}
  # Check log size
  ls -lh ~/.orcbot/daemon.log

  # Rotate logs manually
  mv ~/.orcbot/daemon.log ~/.orcbot/daemon.log.old
  orcbot daemon restart

  # Or truncate
  > ~/.orcbot/daemon.log
  ```
</Note>

## Exit Codes

| Code | Meaning                               |
| ---- | ------------------------------------- |
| 0    | Success                               |
| 1    | Daemon not running (for stop command) |
| 1    | Failed to send stop signal            |

## Related Commands

* [`orcbot run`](/api/cli/run) - Start agent with daemon option
* `orcbot stop` - Stop all OrcBot processes
* `orcbot status` - View overall agent status
* [`orcbot ui`](/api/cli/ui) - Interactive TUI for management