Architecture and identity isolation
Understand how local runtime, gateway sessions, governance, tools, knowledge, and audit fit together.
Maia is a local or privately hosted agent runtime with several interfaces. The CLI, terminal UI, dashboard, gateway, and scheduler all reach the same core capabilities, but each request carries a platform and identity context that changes what Maia may load and do.
Runtime layers
| Layer | Responsibility |
|---|---|
| Interface | CLI, terminal UI, embedded dashboard chat, messaging adapter, cron, API, or editor integration. |
| Session | Conversation history, current working context, model selection, and platform metadata. |
| Identity and governance | Stable user key, roles, teams, file policy, terminal policy, and approval authority. |
| Knowledge | Approved corporate and team context plus isolated personal memory and skills. |
| Agent and tools | Model calls, reasoning loop, enabled toolsets, plugins, MCP servers, and delegated work. |
| Evidence | Runtime logs, approval records, and governance audit events. |
Follow a gateway request
- The messaging adapter validates and normalizes the platform event.
- Gateway admission decides whether the sender may reach Maia.
- Governance resolves the stable identity, roles, and teams.
- Maia loads the permitted shared and personal knowledge layers.
- Platform tool configuration and governance determine the effective tools.
- File, terminal, command, knowledge, or cron approvals are enforced at their relevant control points.
- The response returns through the same platform session and sensitive decisions enter the audit trail.
Understand session isolation
A gateway session belongs to its platform, chat, and user context. Personal memory and skills use a stable identity-derived location, not a shared channel display name. A cron job created by a governed user restores that creator context when it runs.
Several people can participate in one platform channel while retaining different Maia roles and personal knowledge. Authorization must be evaluated for the sender of each event.
Configuration paths
The CLI uses merged Maia defaults and profile configuration. The gateway reads the saved configuration used by its service. When a setting appears correct in one surface but not another, confirm that both processes use the same MAIA_HOME and were restarted after the change.
Use failure boundaries
- A provider failure should not rewrite governance or knowledge.
- A search, MCP, or plugin failure should not prevent the core dashboard from reporting health.
- A denied file or command action should return a controlled result and audit event, not silently broaden access.
- A user-specific session must not leak personal context into another identity's session.