Operate and reference

Operate Maia

Run health checks, inspect logs, back up state, and recover safely.

Operational work starts with health, then logs, then the smallest corrective action. Preserve MAIA_HOME before repairs that could affect state.

Check health

maia status
maia doctor

maia status summarizes the installed runtime. maia doctor diagnoses dependencies, provider configuration, services, and governance posture.

Inspect logs

maia logs
maia logs --follow
maia logs audit

File	Purpose
`<MAIA_HOME>/logs/agent.log`	Application and conversation runtime events.
`<MAIA_HOME>/logs/errors.log`	Warnings and errors requiring attention.
`<MAIA_HOME>/logs/gateway.log`	Messaging gateway startup and delivery events.
`<MAIA_HOME>/logs/audit.jsonl`	Governance-sensitive decisions and administration events.

Logs can contain company context.

Redact secrets and personal or customer data before sharing diagnostic output outside the organization.

Back up Maia

Back up the entire selected MAIA_HOME when you need a complete recovery point. At minimum, preserve configuration, secrets, sessions, corporate and team knowledge, user knowledge, cron state, plugins, and logs required by your retention policy.

Create a pre-update backup with:

maia update --backup

Operate the gateway

maia gateway status
maia gateway restart

After a configuration or credential change, restart the gateway and test from a private channel before announcing service restoration.

Review governance evidence

Audit events cover dashboard access decisions, policy denials, shared-knowledge approvals, cron authorizations, dashboard mutations, and other sensitive control points. Define retention and external export based on your organization's requirements.

Recover safely

Stop the affected Maia process or service.
Copy the current state aside before restoring older data.
Restore the smallest required files from a known backup.
Run maia doctor.
Start the service and test model, gateway, governance, and cron behavior.