Troubleshooting MuxAgent: common issues and how to fix them

Troubleshooting a distributed system with a CLI, a relay, and a mobile app is not the same as troubleshooting a single-process tool. The problem could be in the daemon, the relay connection, the authentication layer, or the agent runtime — and the symptoms often look similar regardless of the root cause.

This guide is organized by symptom. Find the section that matches what you are seeing, follow the diagnostic steps, and apply the fix. Each section includes the specific commands to run, what the output should look like, and what to do when it does not.

Before you start: the diagnostic baseline

Before diving into specific issues, establish a baseline by running these three commands:

muxagent version
muxagent daemon status
muxagent auth status

These tell you:

• Version: Whether you are running a current release
• Daemon status: Whether the daemon is running, its PID, uptime, and the address it is listening on
• Auth status: Whether the machine is authenticated, the machine ID, and the master ID

If any of these commands fail, start with the relevant section below. If all three succeed and your issue is elsewhere, the baseline narrows the problem to a specific area.

Connection issues

Symptom: “cannot connect to daemon” or “daemon not running”

Cause: The daemon process is not running, or its state file is stale.

Diagnose:

muxagent daemon status

If the output says the daemon is not running, check whether a stale state file exists:

ls -la ~/.muxagent/daemon.state.json

Fix — daemon is simply stopped:

muxagent daemon start

The daemon starts in the background, connects to the relay, and begins accepting tasks. If it prompts for authentication (QR code), that means credentials are missing — see the Pairing section below.

Fix — stale state file (PID in state file does not match a running process):

The daemon status command validates that the PID recorded in the state file is actually running. If the process crashed or the machine rebooted without clean shutdown, the state file may reference a dead PID.

muxagent daemon stop    # Cleans up the state file
muxagent daemon start   # Starts fresh

If daemon stop itself fails because the PID is gone, it will still clean up the state file and lock file. Then daemon start will work normally.

Symptom: daemon starts but mobile app shows machine offline

Cause: The daemon started but cannot reach the relay, or the relay connection dropped after startup.

Diagnose:

muxagent daemon status

Check the output for the daemon’s address and uptime. If uptime is very short (a few seconds) and keeps resetting, the daemon is crash-looping — check the logs:

tail -50 ~/.muxagent/daemon.log

Common causes:

• Network issue: The machine cannot reach the relay at wss://relay.muxagent.com/ws. Check firewall rules and proxy settings. The relay uses WebSocket over port 443.
• DNS resolution: If relay.muxagent.com does not resolve, check your DNS configuration.
• Stale credentials: The machine’s authentication may have been revoked from the mobile app. Run muxagent auth status to check.

Fix — network issue:

Verify connectivity to the relay:

curl -s -o /dev/null -w "%{http_code}" https://relay.muxagent.com/health

A 200 response means the relay is reachable. If you get a timeout or connection refused, the issue is network-level (firewall, proxy, VPN).

Fix — revoked credentials:

If muxagent auth status shows the machine is authenticated but the mobile app shows it as offline or revoked:

muxagent auth logout
muxagent auth login

This generates new credentials and triggers a new QR code pairing flow. Scan the QR code from the mobile app to re-establish the machine.

Symptom: connection drops frequently

Cause: WebSocket connections are long-lived TCP connections. They can be interrupted by network changes (WiFi switching, VPN reconnects) or by aggressive connection timeouts in corporate firewalls.

What to know: MuxAgent’s daemon automatically reconnects when the WebSocket drops. A brief disconnect is normal and recoverable — the daemon re-establishes the encrypted channel and resyncs session state. You do not lose session data from a WebSocket disconnect. Session metadata is persisted locally on both the CLI (local storage) and the mobile app (SQLite). The WebSocket only carries the encrypted communication channel.

Diagnose:

tail -100 ~/.muxagent/daemon.log | grep -i "reconnect\|disconnect\|error"

If you see repeated rapid reconnect/disconnect cycles, the problem is likely a corporate firewall terminating idle WebSocket connections.

Fix: Some firewalls and proxies terminate WebSocket connections that appear idle. The daemon sends periodic keepalive pings, but very aggressive timeouts (under 30 seconds) may still cause drops. If this is happening in a corporate environment, work with your network team to allowlist WebSocket connections to relay.muxagent.com.

Pairing problems

Symptom: QR code does not appear during muxagent auth login

Cause: The auth login command generates a cryptographic keypair and encodes the pairing information into a QR code displayed in the terminal.

Diagnose: Check that your terminal supports the QR code rendering. The QR code is rendered using Unicode block characters. Terminals that do not support Unicode well (very old terminal emulators, certain SSH clients) may render it incorrectly.

Fix:

• Use a terminal with full Unicode support (Terminal.app, iTerm2, Windows Terminal, Alacritty)
• If the QR code renders but is unreadable, try resizing your terminal window to make it larger
• If you are using SSH, ensure your SSH client passes through UTF-8 encoding

Symptom: mobile app cannot scan the QR code

Cause: Camera focus issues, screen brightness, or a stale QR code.

Fix:

• Ensure adequate lighting and hold the phone steady at a readable distance
• Increase terminal font size if the QR code is too small for the camera to resolve
• QR codes have a limited validity window — if you have been waiting too long, exit and re-run muxagent auth login to generate a fresh code

Symptom: QR code scans but pairing fails or times out

Cause: The pairing process involves a multi-step handshake between the mobile app and the CLI through the relay. If any step fails, the pairing times out.

Diagnose:

tail -30 ~/.muxagent/daemon.log

Look for error messages related to authentication or WebSocket connections.

Common causes:

• Relay unreachable from either side: Both the CLI and the mobile app need to reach the relay. If the mobile app is on a restricted network (corporate WiFi that blocks WebSocket), pairing will fail even though the CLI can reach the relay.
• Clock skew: The pairing protocol uses time-limited tokens. If the machine’s clock is significantly wrong, tokens may be expired by the time they arrive. Check date on the machine and ensure NTP is working.

Fix: Ensure both devices can reach the relay. Try pairing with the phone on cellular data if corporate WiFi is blocking WebSocket connections.

Symptom: machine paired successfully but does not appear in the mobile app

Cause: There is a brief window after pairing approval where the backend creates the machine record and the daemon connects. If the daemon’s WebSocket connection arrives before the machine record is committed, the relay cannot find the machine.

Fix: Wait a few seconds and pull to refresh in the mobile app. The daemon retries its registration automatically. If the machine still does not appear after 30 seconds, restart the daemon:

muxagent daemon stop
muxagent daemon start

Session issues

Symptom: task starts but agent produces no output

Cause: The agent runtime (Claude Code, Codex) failed to start, or it started but is not producing output through the expected transport.

Diagnose:

muxagent config show

Check that the runtime configuration points to a valid binary. The runtimes section should list the available runtimes and their commands.

muxagent daemon status

Verify the daemon is running and healthy.

Common causes:

• Runtime not installed: The configured runtime binary does not exist at the expected path. MuxAgent does not bundle agent runtimes — they must be installed separately.
• API key missing: Most agent runtimes require an API key (e.g., ANTHROPIC_API_KEY for Claude Code, OPENAI_API_KEY for Codex). Check that the key is set in the environment where the daemon runs.
• Permission issue: The daemon needs execute permission on the runtime binary and read access to the project directory.

Fix: Install the missing runtime, set the required API key, and restart the daemon:

# Check if the runtime binary exists
which claude  # or: which codex
# Set the API key if missing
export ANTHROPIC_API_KEY="your-key-here"
# Restart the daemon to pick up the new environment
muxagent daemon stop
muxagent daemon start

Symptom: session stuck at approval — mobile app does not show the approval request

Cause: The session reached an approval checkpoint but the event did not arrive at the mobile app.

Diagnose:

Check that the daemon is connected to the relay:

muxagent daemon status

If the daemon shows as running and healthy, the issue may be on the mobile app side. Check:

• Is the mobile app in the foreground? Background notifications may be delayed on some devices.
• Is the phone connected to the internet?
• Has the app been force-quit? It needs to be running (or have background refresh enabled) to receive real-time updates.

Fix:

• Open the mobile app and navigate to the machine’s session list — this triggers a resync
• If the approval still does not appear, restart the daemon: the reconnection flow resyncs all pending events

Symptom: session completes but verification fails

Cause: The verification stage ran the checks defined in the task brief and one or more checks did not pass.

What to know: Verification failures are not bugs — they are the workflow system working correctly. The verification stage exists to catch implementation errors before you accept the result.

Fix: Read the verification output to understand what failed. Common causes:

• Tests fail: The implementation introduced a regression. Review the diff and the test output.
• Build fails: The implementation has syntax errors or missing imports.
• Criteria not met: The implementation does not satisfy the task brief’s done definition.

You can re-run the task with a more specific brief, or switch to default config to add an approval gate before implementation, giving you a chance to review the approach before the agent writes code.

Workflow issues

Symptom: agent keeps planning but never implements

Cause: You are using plan-only configuration, or the agent’s plan is being rejected at the review stage.

Diagnose: Check which config you selected:

muxagent config show

In plan-only mode, the workflow graph terminates after the plan stage — that is the intended behavior.

Fix: If you want the agent to implement, use default or autonomous config. If you are in default mode and the agent keeps re-planning, check whether the approval gate is rejecting the plan — the mobile app will show the approval status.

Symptom: task produces poor results despite a good brief

Cause: The workflow config may not match the task’s needs. Or the agent runtime may need more context.

Troubleshooting checklist:

1. Is the write surface bounded? Tasks with unbounded write surfaces (“fix everything in the codebase”) produce worse results than bounded ones (“fix the authentication bug in src/auth/session.go”).
2. Is the done definition falsifiable? “Make the code better” is unfalsifiable. “All tests pass and the function returns the correct result for inputs X, Y, Z” is falsifiable.
3. Are you using the right workflow? Complex tasks need default mode with plan review. If the agent’s plan is wrong and you are using autonomous, it will implement the wrong approach without your input.
4. Is the project config present? MuxAgent supports project-local config (.muxagent/config.json in the project root) for project-specific runtime settings. Run muxagent config show --path to see which config files are active.

Performance concerns

Symptom: agent responses are slow

Cause: Agent response time depends primarily on the upstream API (Claude, OpenAI) and secondarily on the agent runtime’s processing. MuxAgent’s relay and daemon add minimal latency — they are transport layers, not processing layers.

Diagnose:

• Check your internet connection speed to the API provider
• Check whether the task requires reading a large number of files (large codebases slow down the agent’s context building)
• Check the daemon log for WebSocket latency: tail -20 ~/.muxagent/daemon.log

Fix:

• If API latency is the bottleneck, there is nothing to configure on the MuxAgent side — the speed is determined by the model provider
• For large codebases, constrain the task’s read surface in the brief: tell the agent which directories are relevant instead of letting it explore the entire repository
• Ensure the daemon machine has adequate resources (CPU and memory) for the agent runtime

Symptom: high API costs

Cause: Agent tasks consume API tokens proportional to the amount of code they read and generate. Long-running tasks, broad write surfaces, and multiple planning iterations increase costs.

Fix:

• Bound the write surface in your task briefs to prevent the agent from exploring irrelevant code
• Use plan-only mode for analysis tasks instead of full implementation — planning uses fewer tokens than implementation
• Break large tasks into smaller waves — each wave reads less context and generates less output
• Check cost info in the mobile app’s session view to identify which tasks are expensive

Configuration issues

Symptom: muxagent config show does not reflect your changes

Cause: MuxAgent merges configuration from multiple sources in priority order: built-in defaults, user config (~/.muxagent/config.json), project config (./.muxagent/config.json), and environment variables.

Diagnose:

muxagent config show --path

This shows which config files are being loaded and their paths. Check that your changes are in the right file.

Fix:

• If you edited the user config but a project config overrides it, edit the project config instead
• Environment variables (prefixed with MUXAGENT_) override all file-based config
• Use muxagent config init --force to regenerate the default config if yours is corrupted

Symptom: custom runtime not found

Cause: The runtime command in the config does not match an installed binary.

Diagnose:

muxagent config show

Check the runtimes section. Each runtime has a command field that should point to the binary name or path.

Fix:

• Verify the binary exists: which claude or which codex
• If the binary is not in PATH, use the full path in the config
• After editing the config, restart the daemon: muxagent daemon stop && muxagent daemon start

Update issues

Symptom: muxagent update fails

Cause: The update command downloads the latest release from GitHub, verifies its signature, and replaces the binary.

Common causes:

• Network issue: Cannot reach GitHub’s release CDN
• Permission issue: Cannot write to the binary’s location (e.g., /usr/local/bin)
• Windows: Auto-update is not supported on Windows — download the release manually

Fix:

# Check if it's a permission issue
ls -la $(which muxagent)

# If permission denied, use sudo or install to ~/.local/bin
sudo muxagent update
# or
muxagent update --prerelease  # for pre-release versions

If auto-update consistently fails, download the release manually from the GitHub releases page and replace the binary.

Where to get help

If the diagnostic steps above do not resolve your issue:

1. Check the daemon log (~/.muxagent/daemon.log) for detailed error messages
2. Run with verbose auth status (muxagent auth status --verbose) for detailed key and connection information
3. Verify your setup by running through the getting-started guide from scratch on a clean machine — this isolates whether the issue is configuration-specific
4. Check the GitHub issues at the MuxAgent CLI repository for known issues and workarounds
5. File a bug report with the output of muxagent version, muxagent daemon status, and relevant daemon log lines

The most useful bug reports include: what you expected, what actually happened, the full output of the diagnostic commands, and the relevant portion of ~/.muxagent/daemon.log.