Recover local services

Use this runbook when the dashboard is unreachable, the agent daemon is unhealthy, or a normal runtime restart did not return cleanly. Most routine operations belong in Runtime and services.

Always identify the Anima home before acting. The Home row in the Server panel is the easiest source when the dashboard still works. In a terminal, set it explicitly for every command:

export ANIMA_HOME=/absolute/path/to/anima-home

Do not operate a development home when you intend to recover the managed home, or the reverse.

Start with status

npx -y @meetquinn/animactl@latest status

Status reports:

• the installed managed runtime and runtime directory
• the agent and web service state
• process IDs when available
• launchd or systemd ownership when OS services are installed
• the dashboard URL and log paths

Record this output before restarting. A status snapshot distinguishes a service problem from a wrong-home or wrong-version problem.

Read the logs

The selected Anima home owns both service logs:

$ANIMA_HOME/logs/agent.log
$ANIMA_HOME/logs/web.log

Use the agent log for transport, scheduler, queue, worker, and provider-child failures. Use the web log for dashboard and local API failures.

Logs can contain message context, paths, provider diagnostics, and errors. Treat them as sensitive operator data. Do not paste a full log into a public issue; extract the narrow relevant lines and remove secrets or private content.

Choose the smallest recovery action

Symptom	First action	Why
Dashboard unavailable, agents still responding	restart only web	avoids touching agent work
Dashboard works, one agent is hung	use Restart agent after inspecting Activity	scopes the force-stop to that agent
Both local services need a clean restart	top-level restart	uses drain and requeue behavior
Provider login, billing, or quota failure	repair it in the provider	a restart does not change account state
Wrong Home or runtime version	stop and re-run with explicit ANIMA_HOME and package target	fixes the authority, not the symptom

Restart only the web service:

npx -y @meetquinn/animactl@latest restart --only web

Restart both services through the normal continuity path:

npx -y @meetquinn/animactl@latest restart

If agents are running, the normal restart asks them to drain, requeues the affected inbox items, and recovers interrupted items after the worker returns. It does not make already-completed external effects transactional.

Stop and start manually

Use a manual stop/start when you need a quiet filesystem for backup or repair:

npx -y @meetquinn/animactl@latest stop
npx -y @meetquinn/animactl@latest start --no-browser

Wait for agents to become idle before stopping. stop is not a graceful drain command.

An Anima agent turn cannot stop or restart the agent service for its own Anima home. The CLI refuses that self-stop boundary. Run the command from an external human shell. Cross-home control is allowed only when the target home is explicit and differs from the caller's runtime home.

Use force only during an incident

npx -y @meetquinn/animactl@latest restart --force

--force bypasses idle and drain protection. It can terminate the active provider turn. Use it only after you have recorded the running item and accepted that the provider process will be interrupted. The durable inbox record can recover, but external effects that already completed may run again when the item is retried.

Inspect the OS supervisor

When OS services are installed, launchd or systemd owns process restart and startup. Use the service manager to inspect its view, but keep Anima lifecycle changes in animactl so the selected home, runtime path, and service pair stay consistent.

macOS:

launchctl print gui/"$(id -u)" | grep -i anima

Linux:

systemctl --user status | grep -i anima

Homes without OS-managed services use pid files under:

$ANIMA_HOME/run/agent.pid
$ANIMA_HOME/run/web.pid

Do not treat a stale pid file as proof that a process is alive. Use status, then the operating system process table when the two disagree.

Reinstall service definitions

Use this when a managed runtime moved, the generated PATH is stale, or the OS service files were removed:

npx -y @meetquinn/animactl@latest uninstall-services
npx -y @meetquinn/animactl@latest install-services

This changes service definitions, not the Anima home. It does not log in to providers or recreate chat apps.

Verify recovery

Close an incident only after checking all relevant layers:

1. status reports the expected runtime and both intended services running.
2. Server reports the expected Home, version, health, and start time.
3. The web log shows the dashboard started on the expected host and port.
4. The agent log no longer repeats the failure that triggered recovery.
5. Queued work is advancing and no running item remains stranded.
6. One ordinary inbound and outbound message succeeds.

If a filesystem restore or machine move is involved, follow Back up and restore before starting services.