Daemon Management

Manage the Soothe daemon process for background execution.

What is the Daemon?

The Soothe daemon is a background process that:

  • Runs Soothe continuously without a TUI
  • Enables detached execution
  • Supports WebSocket transport
  • Allows multiple clients to connect
  • Maintains thread state

Server Lifecycle

Start Daemon

Start the daemon in the background:

# Start daemon in background
soothed start

# Start in foreground (useful for debugging)
soothed start --foreground

Output (background):

Starting daemon...
Daemon started successfully (PID: 12345, ws://127.0.0.1:8765)

The foreground mode runs run_daemon(..., detached=False) in the current process and does not print the “Daemon started successfully” line — you see the daemon log stream directly until you stop the process.

Check Status

There are two status commands:

  • soothed status — fast local check (no daemon imports, no RPC). Reads the PID file / probes the WebSocket port and prints the local view.
  • soothe status — client-side RPC (queries the running daemon over WebSocket) and renders a unified table including PID, Started (the daemon process start time, an ISO-8601 UTC timestamp), active threads, daemon/core versions, and readiness state.
# Fast local check (no daemon imports)
soothed status

# Rich client-side table (queries the daemon over WebSocket)
soothe status

# JSON output from the client
soothe status daemon --json

soothed status output (running):

Daemon status: running
PID: 12345
WebSocket: ws://127.0.0.1:8765

When the daemon is not running it prints Daemon status: stopped; if the PID file is missing but the port is live it prints Daemon status: running (orphan — PID file missing).

soothe status output (running daemon, unified table):

                          Soothe Status
┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Section   ┃ Setting           ┃ Value                       ┃
┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Connection│ WebSocket URL      │ ws://127.0.0.1:8765         │
│           │ Soothe Home        │ /home/user/.soothe          │
│ Daemon    │ Status             │ Running                     │
│           │ PID                │ 12345                       │
│           │ Started            │ 2026-07-28T08:46:22+00:00   │
│           │ Active Threads     │ 3                           │
│           │ Daemon Version     │ 0.7.0                       │
│           │ Core Version       │ 0.7.0                       │
│           │ Readiness          │ ready                       │
└───────────┴────────────────────┴──────────────────────────────┘

The Started row is the daemon process start time (an ISO-8601 UTC timestamp captured when the daemon enters the running state). It is omitted when the daemon is not live or before the first successful start. With --json the same value is returned under the started_at key.

When the daemon is not reachable, soothe status prints:

                          Soothe Status
┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Section   ┃ Setting           ┃ Value                       ┃
┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Connection│ WebSocket URL      │ ws://127.0.0.1:8765         │
│           │ Soothe Home        │ /home/user/.soothe          │
│ Daemon    │ Status             │ Not running                 │
└───────────┴────────────────────┴──────────────────────────────┘

Hint: Start with 'soothed start'

Stop Daemon

Gracefully stop the daemon:

soothed stop

Output:

Stopping daemon (PID: 12345)...
Daemon stopped successfully

Restart Daemon

Restart the daemon:

soothed restart

Attach to Daemon

Note: To reconnect to a running daemon, use:

# Continue last active loop via daemon
soothe loop continue  # CLI auto-connects to running daemon

# Continue specific loop via daemon
soothe loop continue <loop-id>  # CLI auto-connects to running daemon

This opens the TUI and connects to the already-running daemon.

Detached Execution

Detach from TUI

Keep daemon running after closing TUI:

# In TUI
/detach

# Or use keyboard shortcut
Ctrl+D

The daemon continues running in the background.

Reattach Later

Reconnect to the daemon:

# Continue via running daemon
soothe loop continue  # CLI auto-connects to running daemon

When to Use Daemon Mode

Background Processing

Run long tasks without keeping the TUI open:

# Start daemon
soothed start

# Run task in background
soothe -p "Analyze the entire codebase" &

# Detach and close terminal
# Task continues running

Multiple Clients

Connect multiple clients to the same daemon:

  • CLI client
  • TUI client
  • Web UI (via WebSocket)

24/7 Availability

Keep Soothe running continuously:

  • Always ready for queries
  • No startup latency
  • Maintains context and memory

Logs

Daemon logs are stored in:

~/.soothe/logs/
├── soothed.log          # Daemon transport, sessions, routing (soothe_daemon.*)
├── soothe.log          # In-process agent core (soothe.*, soothe_plugins.*)
└── soothe-cli.log      # CLI client (when using soothe TUI/CLI)

View Logs 

# Daemon server (WebSocket, session lifecycle)
tail -f ~/.soothe/logs/soothed.log

# Agent execution inside the daemon process
tail -f ~/.soothe/logs/soothe.log

# View specific thread log
tail -f ~/.soothe/logs/threads/abc123.log

Debug Mode

Enable verbose logging:

export SOOTHE_DEBUG=true
soothed start

Configuration

Configure daemon behavior in ~/.soothe/config/daemon.yml:

# Transport configuration
transports:
  websocket:
    enabled: true
    host: "127.0.0.1"
    port: 8765

# Concurrency — per-request wall-clock cap (default 14 days; 0 = no timeout)
thread_pool:
  request_timeout_seconds: 1209600

# Legacy / optional fields (may appear in older configs)
max_concurrent_threads: 100
thread_max_age_hours: 24

# Logging (agent config in nano.yml → observability)
# log_file_level: INFO  # DEBUG, INFO, WARNING, ERROR

Monitoring

Resource Usage

Monitor daemon resource usage:

# Check memory and CPU
ps aux | grep soothe

# Use system monitor
htop -p $(pgrep -f "soothed")

Health Checks

Use the daemon doctor command:

soothed doctor

Response:

{
  "status": "healthy",
  "uptime": 7200,
  "active_threads": 3,
  "memory_mb": 256
}

Troubleshooting

Daemon Won’t Start

Error: Address already in use

Solution: Port 8765 is already in use by a previous instance

soothed stop
soothed start

Daemon Not Responding

Solution: Restart the daemon

soothed stop
soothed start

Can’t Connect to Daemon

Error: No daemon running

Solution: Start daemon first, then use loop continue

soothed start
soothe loop continue  # CLI auto-connects to running daemon