Agent Lifecycle

Creating, starting, stopping, and removing an agent — and what changes once you install it as a service.

mur agent create coach --model llama3.2:3b   # create
mur agent start coach                        # start
mur agent stop coach                         # stop, and keep it stopped
mur agent restart coach                      # restart onto an upgraded runtime
mur agent remove coach                       # unregister (data survives)
mur agent remove coach --purge               # unregister and delete its data

Supervised vs unsupervised

By default mur agent start spawns the runtime as a detached process. It runs until something stops it — a crash, a logout, a reboot — and nothing brings it back.

mur agent install-service <name> writes a launchd (macOS) or systemd --user (Linux) unit, so the agent starts at login and restarts if it exits:

mur agent install-service coach
mur agent install-service coach --dry-run    # print the unit, write nothing

This changes what the other commands do:

Why stop unloads it. The service sets KeepAlive, so the supervisor restarts the runtime the instant it exits. Signalling the process alone would only swap its pid — the agent would still be running a second later. stop therefore takes the agent out of the supervisor's hands first, and confirms nothing came back before reporting success.

The service descriptor stays on disk, so mur agent start brings the agent back and it returns at the next login.

Removing an agent

remove keeps the agent's data. ~/.mur/agents/<name>/ — its profile, identity keypair, skills, conversation history, companion inbox — is left in place, and the command prints where:

Removed agent 'coach' (data preserved at /Users/you/.mur/agents/coach)

Pass --purge to delete that directory as well. There is no undo.

Two guards run first:

• Still running — removal refuses. Stop it first.
• Unread companion messages — removal refuses so you don't lose them. Read them with mur agent companion inbox <name> --unread-only, or pass --force.

Checking state

mur agent list                          # every agent, with status, uptime, pid
mur agent status coach                  # one agent in detail
mur agent restart --stale --dry-run     # which agents run an older binary than their own symlink

restart --stale compares the build recorded in each agent's running.lock against the binary that agent's own ~/.local/bin/mur_agent_<name> symlink points to — not a single global runtime — because that symlink is what the service actually execs, and a dev checkout, an older keg, and mur update's copy can coexist. An agent is stale only when its own binary differs, so a mixed fleet is reported per agent instead of being dragged toward one baseline.

Agents with no lock file are reported, not skipped: a stopped agent appears as not examined (N not running), and one that has a service installed but isn't running gets a ⚠ warning to mur agent start it.

After upgrading MUR, mur update --restart-agents does the refresh and the restart together, and prints a per-agent summary with the build id on each side of the arrow.