Operate and reference

Configuration reference

Find Maia's primary files, directories, configuration sections, and secret-handling rules.

Maia uses profile-aware paths. The default home is ~/.maia; set MAIA_HOME when a deployment needs a different isolated data root.

Primary files and directories

Path	Purpose
`<MAIA_HOME>/config.yaml`	Non-secret runtime, gateway, governance, tool, memory, and approval settings.
`<MAIA_HOME>/.env`	API keys, tokens, passwords, and other secrets.
`<MAIA_HOME>/logs/`	Runtime, error, gateway, and audit logs.
`<MAIA_HOME>/skills/`	Local profile skills.
`<MAIA_HOME>/memories/`	Local profile memory.
`<MAIA_HOME>/corporate/`	Approved company-wide knowledge.
`<MAIA_HOME>/teams/`	Approved team knowledge.
`<MAIA_HOME>/users/`	Isolated gateway-user knowledge.

Common configuration sections

Section	Controls
`model`	Primary provider, model, endpoint, and reasoning options.
`tools`	Enabled and disabled toolsets by platform.
`gateway`	Messaging behavior and platform configuration.
`governance`	Tenant, people, roles, teams, folders, and terminal policy.
`dashboard`	Protected dashboard authentication and role gates.
`knowledge`	Shared-memory and shared-skill approval policy.
`cron`	Scheduler behavior.
`approvals`	Command approval mode and behavior.
`observability`	Audit log, retention, redaction, and export.

Keep settings and secrets separate

Simple rule.

If disclosure would grant access, put the value in the managed secret flow. If the value changes behavior without granting access, put it in config.yaml.

Configure working directories

The local CLI uses the process working directory. Messaging uses terminal.cwd from config.yaml. Set the messaging directory to a governed path and define folder policy for the identities that will use it. Gateway shell/code sessions are forced into per-user Docker or Podman containers, so the server needs a working secure runtime for Full automation; Maia enters Restricted mode and blocks command execution if isolation cannot start.

Validate configuration changes

maia status
maia doctor

Gateway credentials, secrets, or tool-runtime changes may require restarting the affected service. Governance membership and file-policy changes do not: Maia replaces the affected user's sandbox when their next gateway request starts. Test every change with the lowest-privileged identity impacted.