Daemon Integration

Advanced guide for working with the Khaos Machine background services.

Overview

Khaos Machine runs two background daemons:

• khaosd — the main daemon that serves the web dashboard and manages analysis jobs
• khaos-wfl — the workflow daemon that orchestrates background analysis and event streaming

Both start automatically when you launch Khaos Machine.

Daemon Lifecycle

macOS

The menu bar app manages daemon lifecycle automatically. Daemons are registered as LaunchAgents:

# Check daemon status
launchctl print gui/$(id -u)/studio.khaos.khaosd

# View registered agents
launchctl list | grep khaos

Linux

Daemons run as systemd user services:

# Check status
systemctl --user status khaos-wfl

# Restart
systemctl --user restart khaos-wfl

Windows

Start and stop daemons from the command line:

khaosd-ctl start
khaosd-ctl stop

Health Checks

Check Daemon Health

# Find the daemon port
cat ~/.khaos/runtime.json | python3 -c "import json,sys;print(json.load(sys.stdin)['port'])"

# Health check
PORT=$(python3 -c "import json;print(json.load(open('$HOME/.khaos/runtime.json'))['port'])")
curl -s "http://localhost:${PORT}/api/health" | python3 -m json.tool

Check WFL Daemon

# Ping the workflow daemon
ls -la ~/.khaos/wfl.sock  # Socket should exist when running

Event Streaming

The workflow daemon streams real-time events via Server-Sent Events (SSE). The web dashboard uses this for live progress updates.

Key event topics:

Topic	Description
wfl.analysis.started	Analysis job started
wfl.analysis.progress	Progress update (completed/total)
wfl.analysis.completed	Analysis finished
wfl.signal.created	New feedback signal generated

Log Locations

All persistent logs are stored in ~/.khaos/logs/:

Log	File	Format
Daemon HTTP lifecycle	khaosd.log	NDJSON
Job progress and errors	khaosd-console.log	NDJSON
WFL daemon events	khaos-wfl.log	NDJSON
TUI activity	khaos-tui.log	Text
Menu bar app (macOS)	khaos-machine.log	Text

Viewing Logs

# Recent errors
tail -50 ~/.khaos/logs/khaosd-console.log | grep '"level":"error"'

# Follow daemon log
tail -f ~/.khaos/logs/khaosd.log

# Follow WFL log
tail -f ~/.khaos/logs/khaos-wfl.log

Configuration

Settings File

Global settings are stored in ~/.khaos/config.json. Edit via the Settings page in the web dashboard.

API Keys

API keys for cloud providers are stored in ~/.khaos/keys.json with 0600 permissions (owner-only read/write).

Runtime State

The daemon writes runtime information to ~/.khaos/runtime.json (port, PID) on startup. This file is ephemeral and recreated each time the daemon starts.

Troubleshooting

Daemon Won't Start

1. Check if another instance is already running:

   ps aux | grep khaosd

2. Check for port conflicts:

   cat ~/.khaos/runtime.json  # See what port it wants
   lsof -i :PORT_NUMBER       # Check if port is taken

3. Check logs for errors:

   tail -20 ~/.khaos/logs/khaosd.log

Stale Socket

If the WFL daemon crashed, it may leave a stale socket file:

rm ~/.khaos/wfl.sock
# Then restart the daemon

Next Steps

• Background Services — more about the workflow daemon
• Troubleshooting — help with common issues