Skip to main content

​
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

# 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. 
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. 
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). 
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. 
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: 
tail -f ~/.orcbot/daemon.log

​
Lock File

Location: ~/.orcbot/orcbot.lock Contents: JSON with instance metadata 
{
  "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

# 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

# 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

# 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

# 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

# These are equivalent:
orcbot run --daemon
orcbot daemon start

# Both create daemon process

​
orcbot stop

# Stops ALL OrcBot processes including daemon
orcbot stop

# More targeted daemon-only stop:
orcbot daemon stop

​
orcbot status

# General status (includes daemon check)
orcbot status

# Daemon-specific status
orcbot daemon status

​
Troubleshooting

Daemon Won’t Start: If orcbot run --daemon fails with “already running” error:
# 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
Daemon Won’t Stop: If orcbot daemon stop doesn’t stop the process:
# 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
Daemon Logs Growing Large: Daemon logs are append-only and can grow over time:
# 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

​
Exit Codes

CodeMeaning
0Success
1Daemon not running (for stop command)
1Failed to send stop signal
  • orcbot run - Start agent with daemon option
  • orcbot stop - Stop all OrcBot processes
  • orcbot status - View overall agent status
  • orcbot ui - Interactive TUI for management