Run Brains with a recovery path

Security and the trust boundary

Brains is alpha software for one local operator, not a multi-tenant server or process sandbox. Keep listeners on loopback. Protected /v1/* and HTTP MCP routes require authentication; the bootstrap key carries install-wide authority. Keep keys, binding files and state out of repositories and public logs.

The audit chain records supported governed paths, not every external harness action. A failed verification is an integrity incident; do not clear or rewrite the signed head to make it pass.

brains-ai credentials doctor
brains-ai audit-verify

Read the security policy and authentication contract before exposing a listener.

Diagnose before changing state

brains-ai readiness
brains-ai wire --status
brains-ai db diagnose
brains-ai queue-health status

Inspect component results for database integrity, authenticated MCP, listeners, queues and recovery. /health is only gateway liveness. A ready response does not establish browser journeys, ingress or a successful live restore. Repair commands default to dry-run; review their plan before explicit apply.

Upgrade the installation you actually use

Back up first and stop the owned stack before replacing its installation. For pipx, use the sequence below, then restart using your existing foreground or service configuration and check readiness.

pipx upgrade brains-ai
brains-ai db migrations
brains-ai db migrate
brains-ai version

For a managed virtual environment, use its python -m pip install --upgrade brains-ai; for uv, use uv tool upgrade brains-ai. brains-ai upgrade is specifically for editable Git-checkout installs: it pulls, reinstalls and applies migrations. Do not edit historical migrations to bypass a failure.

Background services are opt-in

User-service definitions target Task Scheduler, launchd and systemd-user. Review the definition before installing; do not run serve-all beside a service using the same state and ports.

brains-ai service install --help
brains-ai service status
brains-ai service logs

Windows upgrades: reinstall an existing task with brains-ai service install to refresh its state-directory binding and runner. Preserve custom label and port options, then inspect service status for effective endpoints. Only the selected state root is captured, not all installing-shell variables or secrets.

A successful native manager cycle does not establish login or reboot persistence. The full service contract explains lifecycle and cleanup limits.

Verify a backup before restore

brains-ai backup ./brains-backup.tar.gz
brains-ai backup-inspect ./brains-backup.tar.gz
brains-ai db verify-backup ./brains-backup.tar.gz

Backups use SQLite's online backup API, not a raw copy of live WAL files. Manifest inspection is not an isolated restore test. Brains does not schedule backups; retention, encryption and offsite custody remain operator responsibilities.

Full recovery sequence: backup, restore and rollback. Positional path syntax is verified against the tagged CLI source.