Configure Daemon

The daemon is the core component of Mopheus runtime, responsible for receiving and executing agent tasks. After configuring the daemon, your machine becomes a runtime that can host AI agents.

Prerequisites

Login

The daemon reuses the CLI's authentication, so mopheus login must succeed on this machine before the daemon can register. If you already completed this in Install CLI Tools, skip ahead to Start Daemon.

Configure Server URL

If you are using a self-hosted Mopheus instance, point the CLI at your backend:

mopheus config set server_url https://your-mopheus.example.com

Authenticate

# Option A: Interactive API Token input (create at Settings → API Tokens in web UI)
mopheus login --token

# Option B: Email + password login, CLI automatically creates a long-lived API Token
mopheus login --email your@email.com --password yourpassword

Verify login succeeded:

mopheus workspace list

If the list comes back (even empty), you are connected.

Start Daemon

mopheus daemon start

Run the daemon as a regular system user. Direct root daemon launches are rejected because agent subprocesses inherit the daemon's filesystem and network privileges, and root-owned task directories later block normal-user runs. In a controlled environment that intentionally requires a root daemon process, opt in explicitly:

mopheus daemon start --allow-root

This flag applies to the daemon process, not to management commands. A root user can still run mopheus daemon start or restart to manage an installed system-level service; Mopheus delegates those operations to systemd.

On first run, the daemon:

1. Creates a stable machine ID at ~/.mopheus/daemon.id (reused on every subsequent start)
2. Scans for known provider CLIs (claude, kimi-code, agy) and any custom binaries set via env var
3. Connects to the server and registers, listing every discovered provider CLI
4. Starts accepting tasks for any compatible agent
5. Sends periodic HTTP heartbeats every 30 seconds while it is running

Verify the daemon is running:

mopheus daemon status

Within a few seconds, your machine appears under Runtimes in the sidebar, with one row per discovered provider.

Keep It Running

For development, leave the foreground mopheus daemon start process running in a terminal.

For longer-running setups, run the daemon under a process supervisor so it restarts after reboots and crashes.

Recommended: mopheus daemon install

The simplest way to set up the systemd service is mopheus daemon install. It generates the unit file and an env template for you:

# Install a systemd service (root → system service at /etc/systemd/system/mopheus-daemon.service,
# non-root → user service at ~/.config/systemd/user/mopheus-daemon.service)
mopheus daemon install

# Enable on boot and start immediately
mopheus daemon install --enable --start

# Pass extra 'daemon start' flags after --
mopheus daemon install -- --agent-idle-watchdog 0s

This writes the service unit and an env file, then runs systemctl daemon-reload. Use --enable to start on boot and --start to launch it right away. For non-root (user) services, the installer checks linger status; if disabled (default: no), run sudo loginctl enable-linger $USER so the user-level systemd service continues running after all SSH sessions are closed and starts without an active login session.

A system-level unit installed as root includes --allow-root in ExecStart, making its root daemon process an explicit opt-in. Existing systemd-owned root daemons remain compatible because Mopheus recognizes systemd invocation metadata during upgrades. User-level units do not include the flag. Prefer a user-level service unless the daemon specifically requires system-wide privileges.

Agent Task Physical Resource Telemetry and cgroup v2 Delegation

The Mopheus daemon automatically captures and persists an end-state physical resource telemetry profile (resource_telemetry) for every completed or failed agent task. The system provides two built-in telemetry modes to ensure reliable data recording across all environments:

1. Kernel Mode (cgroup_v2): On Linux systems with cgroup v2, the daemon creates dedicated kernel sub-slices for each task. Upon task termination, it reads kernel hardware counters in sub-milliseconds (under 1ms) with zero polling overhead and zero missed short-lived processes, capturing precise CPU execution time, stack/cache memory breakdowns, disk I/O throughput/IOPS, and kernel PSI pressure stall metrics.
2. Sampler Fallback Mode (sampler): On macOS or Linux systems without cgroup delegation, the daemon automatically and transparently falls back to process-tree periodic sampling. Reusing the 2-second watchdog loop, it continues to record lifecycle peak physical memory (Peak Memory) and peak concurrent processes (Peak Procs), guaranteeing baseline physical telemetry even in unprivileged, zero-configuration environments.

Comparison of Telemetry Modes in Mopheus

How to Enable Full Kernel Mode (cgroup_v2) on Linux

When running the daemon as a regular non-root user on Linux (e.g. Ubuntu, Debian, Arch, WSL 2), configure systemd cgroup delegation in one step:

sudo mkdir -p /etc/systemd/system/user@.service.d
sudo tee /etc/systemd/system/user@.service.d/delegate.conf <<'EOF'
[Service]
Delegate=yes
EOF
sudo systemctl daemon-reload

Tip: Even without this delegation configured, the Mopheus daemon operates normally in sampler fallback mode and records baseline physical profiles without failing or interrupting agent tasks.

Manual systemd setup (fallback)

If daemon install is unavailable or you need full control, create the unit file by hand. Create an environment file to hold your configuration:

mkdir -p ~/.mopheus
tee ~/.mopheus/daemon.env > /dev/null <<'EOF'
# MOPHEUS_DAEMON_DEVICE_NAME=my-server
# MOPHEUS_WORKDIR=~/mopheus_workspace
EOF
chmod 600 ~/.mopheus/daemon.env

# /etc/systemd/system/mopheus-daemon.service
[Unit]
Description=Mopheus agent runtime daemon
After=network.target

[Service]
Type=simple
ExecStart=%h/.local/bin/mopheus daemon start --foreground
Restart=always
RestartSec=5
# Wait up to 45s for in-flight tasks to finish; systemd force-kills after 50s.
Environment="MOPHEUS_DAEMON_SHUTDOWN_DRAIN_TIMEOUT=45s"
TimeoutStopSec=50s
User=mopheus
Environment="HOME=/home/mopheus"
# To tune runtime behaviour, pass parameters via environment variables:
# Environment="MOPHEUS_DAEMON_MAX_CONCURRENT_AGENT_TASKS=5"
# Environment="MOPHEUS_DAEMON_DEVICE_NAME=DBA-Workstation"

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now mopheus-daemon
journalctl -u mopheus-daemon -f

Configuration

Environment variables tune the daemon's behaviour. All have safe defaults.

Connection

Runtime Identity

Runtime Behaviour

Provider CLI Paths

Working Directory and Logs

Health Endpoint

The daemon exposes GET http://127.0.0.1:19515/health for local health checks. This port cannot be overridden via environment variable; it is derived internally from the CLI profile (default profile uses 19515, other profiles offset by the hash of the profile string). Use it for liveness probes in containers or service supervisors.

Stop Daemon

To stop the daemon cleanly:

mopheus daemon stop

The daemon sends a deregister request and the runtime flips to Offline in the UI.

Troubleshooting

Daemon does not appear in the Runtimes list

• Check the daemon's log output — connection errors show up immediately
• Confirm mopheus login succeeded by running mopheus ticket list
• Confirm MOPHEUS_SERVER_URL matches the host you logged in against
• If you are behind a proxy, set HTTPS_PROXY so the WebSocket upgrade can reach the server

Runtime appears but tasks are not picked up

• Verify the provider CLI is on $PATH (which claude) or that the override env var points at a working binary
• Check that the agent's provider CLI matches what the runtime advertises — a Claude agent will not run on a kimi-code-only runtime
• Check the agent's status: if it is Error, clear the error first and re-run the task

Newly installed provider CLI does not appear in the runtime list

The daemon re-probes provider CLIs every 30 seconds, no restart is required. A newly installed CLI will be discovered automatically within one probe cycle (30 seconds). If it does not appear after a while, check that the CLI is on $PATH and is executable.

Health endpoint

# Check whether the daemon is alive
curl http://127.0.0.1:19515/health