orcbot daemon

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:

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

restart

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

orcbot daemon restart

Behavior:

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

Daemon Process Details

PID File

Location: ~/.orcbot/orcbot.pid Contents: Plain text integer (process ID)

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

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

Running

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

Stopping

SIGTERM signal sent to daemon process
Graceful shutdown initiated:
- Current action completes
- Memory flushed to disk
- Channels disconnected
- Gateway stopped (if running)
PID file removed
Lock file removed
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

Code	Meaning
0	Success
1	Daemon not running (for stop command)
1	Failed 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

CLI Commands

Core Skills

Configuration

Overview

Usage

Subcommands

status

stop

start

restart

Daemon Process Details

PID File

Log File

Lock File

Examples

Start and Monitor Daemon

Graceful Restart

Force Stop Stuck Daemon

Clean Up After Crash

Process Lifecycle

Starting

Running

Stopping

Integration with Other Commands

orcbot run

orcbot stop

orcbot status

Troubleshooting

Exit Codes

​Overview

​Usage

​Subcommands

​status

​stop

​start

​restart

​Daemon Process Details

​PID File

​Log File

​Lock File

​Examples

​Start and Monitor Daemon

​Graceful Restart

​Force Stop Stuck Daemon

​Clean Up After Crash

​Process Lifecycle

​Starting

​Running

​Stopping

​Integration with Other Commands

​orcbot run

​orcbot stop

​orcbot status

​Troubleshooting

​Exit Codes

​Related Commands

Overview

Usage

Subcommands

status

stop

start

restart

Daemon Process Details

PID File

Log File

Lock File

Examples

Start and Monitor Daemon

Graceful Restart

Force Stop Stuck Daemon

Clean Up After Crash

Process Lifecycle

Starting

Running

Stopping

Integration with Other Commands

orcbot run

orcbot stop

orcbot status

Troubleshooting

Exit Codes

Related Commands