Configure users and governance

Governance is always active and converts an authenticated platform identity into an authorized Maia user. Roles determine what the user may do; teams determine which approved team knowledge the user receives. A role admits the person to the bot but grants no files by itself.

Configure governance in the recommended order

1. Set a stable tenant identifier. Governance is already enforced and cannot be disabled.
2. Define the role hierarchy and keep the default role minimally privileged.
3. Create teams under Teams for real access and knowledge boundaries.
4. Add gateway identities under People and select their teams.
5. Grant narrow file access to people, teams, or reusable folder policies.
6. Test the policy with a non-administrator account.

Apply a least-privilege baseline

governance:
  enabled: true
  tenant_id: acme-corp
  default_role: viewer
  role_hierarchy: [viewer, operator, manager, admin]
  teams: {}
  terminal:
    allowed_roles: [operator]
    approver_roles: [manager, admin]

approvals:
  mode: smart

observability:
  audit_log_enabled: true

The onboarding page can apply the security baseline, after which you complete the tenant-specific people, teams, and folder policies. File access with no matching grant is always denied; this default cannot be changed. Gateway terminal, code execution, and delegated agents use the same grants as Docker or Podman mounts and fail closed rather than falling back to host access. Onboarding reports Full automation or links to the per-system Restricted mode setup.

Add a person

1. Open Governance → People.
2. Select the pending gateway identity or enter its exact platform:user_id.
3. Add a recognizable name for administration.
4. Assign the lowest role that supports the person's work.
5. Select only teams that already exist in the Teams tab.
6. Add direct file or folder access only when the person needs a genuine individual exception.
7. Save and ask the user to run /whoami.

Administer Maia through an authenticated message

A system admin can ask Maia to admit users to the gateway, create or update governed identities, assign roles and teams, manage direct file grants, delegated roots, and folder policies. Maia uses a structured administration tool instead of editing configuration files through shell commands.

The requester is taken only from the authenticated gateway message, never from a name or identity written in the prompt. Governance is checked again on every action. Team managers may manage file policy only below their delegated root and only for users and teams in their scope. Provider secrets and dashboard login credentials remain server-only, and both successful and denied actions are audited.

Manage teams as first-class access groups

1. Open Governance → Teams and create the team.
2. Select its members from the governed people list.
3. Add the team's direct file or folder grants.
4. Configure a delegated root only when team managers should administer a bounded server folder.
5. Save, then verify access with a member account.

A team cannot be deleted while people, file policies, or a delegated root still reference it. Remove those references first so the deletion is explicit and auditable.

Use roles consistently

Verify the policy

For every rollout, test with a real non-admin identity:

• a normal message;
• an allowed file read;
• a denied folder;
• a write that requires confirmation;
• a terminal or configuration action outside the user's role.