What Is the Daemon

The daemon is a background process started by mopheus daemon start. It is the central link in Mopheus's task-execution chain.

In short: the daemon is the engine, and the provider CLI is the executor.

The daemon itself does not do the actual work (write code, query databases, etc.). Its core job is orchestration: discover provider CLIs on your machine, receive tasks from the server, dispatch them to the appropriate provider CLI for execution, and relay the results back to the server.

When installed as a systemd service, the service cgroup owns the daemon lifecycle. Each Linux agent task uses its own process group and, when available, a delegated cgroup v2 scope for cancellation. The daemon does not create an additional supervisor process per task.

One daemon per host A daemon can discover multiple Provider CLIs Each Provider CLI can be referenced by multiple agents An agent can handle multiple tasks concurrently (subject to maxConcurrentAgentTasks) A "task" is an execution record generated each time an agent is triggered via a ticket or chat

What the Daemon Does

Daemon, Runtime, and Provider CLI

These are the three most commonly confused concepts in Mopheus. One-sentence summary:

• Provider CLI (e.g. ClaudeCode, KimiCode) = The executor — the program that actually runs the task
• Daemon (mopheus daemon start) = The engine / dispatcher — discovers executors, receives tasks, dispatches them, collects results
• Runtime = The ledger — the Mopheus-side mapping record of a provider CLI

A concrete example:

1. You install claude (ClaudeCode CLI) on your laptop
2. You run mopheus daemon start
3. The daemon discovers that claude exists on your machine
4. The daemon tells the server: "I have a claude on this machine"
5. The server creates a runtime record: "claude @ your-laptop"
6. The server dispatches a task to the daemon
7. The daemon hands the task to claude to execute
8. Claude writes code, queries the database, edits files (the actual execution)
9. The daemon relays claude's output back to the server

Each machine needs (and can only have) one daemon running. The UI may show multiple runtime rows, but there is always only 1 daemon process in the background.

Heartbeat

The daemon uses a set of background goroutines to maintain its connection to the server and keep runtime state in sync:

1. Fetch workspaces — the daemon periodically pulls the current user's workspace list from the server.
2. Register runtimes — for each workspace × provider CLI combination, it registers an owner-scoped runtime record with the server. New records start disabled and must be enabled by their runtime owner in each workspace.
3. Periodic heartbeat — each runtime has its own coroutine that sends heartbeat every 30 seconds. Coroutines are independent — a slow heartbeat on one runtime never delays another.
4. Server-side handling & dead runtime cleanup — the server refreshes heartbeat state only for enabled runtimes; disabled runtimes stay unavailable even if the daemon keeps running. If an enabled runtime has no heartbeat for 90 seconds, it is marked offline. On the daemon side, receiving a 404 (runtime gone) triggers a 30s merge window for re-registration; if re-registration still fails, it backs off 60s before retrying. Cleanup does not remove runtime rows that still have active tasks or direct agent bindings. If cleanup removed the row, its replacement starts disabled and requires owner activation again.

Concurrency

Task concurrency, scheduling, timeouts, retries, stopping, and restart recovery are documented together in Daemon Task Execution.

Daemon Lifecycle

# Start — scan provider CLIs, register runtimes, begin receiving tasks
mopheus daemon start

# Check status — is it running, which workspaces are connected
mopheus daemon status

# View logs — debug connection errors, task execution issues
mopheus daemon logs

# Stop — gracefully deregister all runtimes, they show Offline in the UI
mopheus daemon stop

# Restart — wait for running tasks to finish, then start again
mopheus daemon restart

Work Directory GC

Task directories, success-only worktree cleanup, and periodic GC are documented in Work Directories and Cleanup.

Filesystem Sandbox

The sandbox mount boundary, collaboration scope within a workspace, cross-workspace isolation, personal configuration delivery, and fallback behaviour are documented in Filesystem Sandbox.

Runtime task resource guard and watchdog

The monitor, enforcement model, configuration hierarchy, and diagnostics are documented in Runtime Resource Guard.

Troubleshooting

Runtimes do not appear after starting the daemon

• Check that the provider CLI is on $PATH: which claude
• View the daemon logs: mopheus daemon logs
• Confirm mopheus login succeeded: mopheus ticket list

Tasks are dispatched but never run

• Check daemon status: mopheus daemon status
• Verify the provider CLI is functional: claude --version
• Check whether concurrency slots are full: the daemon defaults to 20 concurrent tasks maximum

Daemon shows offline

• The daemon sends a heartbeat every 30 seconds; if none arrive for ~90 seconds the runtime shows offline
• Check network connectivity: curl $MOPHEUS_SERVER_URL/health
• If behind a proxy, set HTTPS_PROXY

Task usage is stored as one idempotent final snapshot per (agent_task_id, model). Repeated CLI reports replace the task snapshot; workspace and agent daily totals remain cumulative across distinct tasks.

Command-Line Reference

Common CLI commands for daemon lifecycle management:

mopheus daemon start                        # Start daemon in background (auto-discovers Provider CLIs)
mopheus daemon start --foreground           # Run daemon in foreground with live console logs
mopheus daemon status                       # Check daemon status, PID, and discovered providers
mopheus daemon logs                         # View daemon log history
mopheus daemon logs -f                      # Stream live daemon logs
mopheus daemon restart                      # Restart daemon
mopheus daemon stop                         # Gracefully stop daemon (waits for active tasks)