Enable full governed automation

Maia does not require Docker or Podman for its core application. A secure container runtime is required for command-capable requests made by governed gateway users: terminal commands, Python or other code, Office automation, and delegated agents that use those tools.

Why the secure runtime matters

Governance decides which host paths a person may read or change. The secure runtime is the second boundary: Maia starts a Linux container for that person and mounts only the paths Governance grants. Read-only grants are mounted read-only. Without that boundary, a shell or Python process could see more of the host than the file policy allows.

Understand the two operating modes

Mode	Available	Unavailable
Full automation	Chat, gateways, Governance, approvals, audit, safe file tools, governed terminal/code, Office/Python automation, and delegated command execution.	Nothing is blocked by runtime readiness; file policy and approvals still apply.
Restricted mode	Chat, gateways, Governance, approvals, audit, path-checked file reads, and supported staged file changes.	Gateway terminal, arbitrary shell/code, command-based Office automation, and delegated agents that need those tools.

Restricted mode is a supported safe state, not broken file authorization. A missing runtime does not grant extra access and does not require you to remove or recreate file policies.

Configure it during installation

The Maia installer checks runtime readiness after installing the application:

1. If Docker or Podman is ready, the installer confirms Full automation.
2. If it is missing on a supported Linux distribution, the installer can offer to install rootless Podman through the system package manager. It asks before using sudo.
3. On Windows/WSL and macOS, the installer prints the required operating-system or desktop step. It does not silently accept software licenses, change Docker Desktop settings, or install a macOS system package.
4. If you skip or cannot finish the step, Maia installation completes in Restricted mode.

Configure or repair it later

maia secure-runtime status
maia secure-runtime setup

status explains the current mode, why it matters, what remains available, what is blocked, and the exact steps for the detected system. setup performs only the safe automated portion and leaves desktop or license decisions to the operator.

maia update also checks readiness after updating. The update itself remains successful in Restricted mode and never installs system software unattended. If the summary reports Restricted mode, run maia secure-runtime setup.

Windows with WSL2

1. Install Maia inside a WSL2 distribution such as Ubuntu. Native PowerShell is not the Maia runtime.
2. In Windows, install and start Docker Desktop and use its WSL 2 backend.
3. Open Docker Desktop Settings → Resources → WSL Integration.
4. Enable the same distribution that runs Maia, then choose Apply & restart.
5. Return to the WSL terminal and verify both client and server:

   docker version

6. Recheck Maia:

   maia secure-runtime status

Linux

Rootless Podman is the preferred Linux path because it can run containers as the Maia user without a permanent root daemon. Start with the guided command:

maia secure-runtime setup

For a manual installation, use the command for your distribution or follow the official Podman installation guide:

# Ubuntu / Debian
sudo apt-get update
sudo apt-get -y install podman

# Fedora / CentOS Stream / compatible RHEL family
sudo dnf -y install podman

# Arch / Manjaro
sudo pacman -S --noconfirm podman

# openSUSE
sudo zypper --non-interactive install podman

Verify as the same user that runs Maia:

podman version
podman info
maia secure-runtime status

Docker Engine is also supported. Install it from the official Docker Engine guide, start the engine, verify that the Maia user can run docker version, then recheck Maia.

macOS

macOS needs a small Linux virtual machine because Linux containers require a Linux kernel.

1. Install Podman with the official macOS installer. Docker Desktop is also supported.
2. Create the Podman machine once:

   podman machine init

3. Start it now and after a later shutdown when needed:

   podman machine start

4. Verify and recheck Maia:

   podman version
   maia secure-runtime status

If Podman is already installed but its machine is stopped, maia secure-runtime setup can offer to start it. If you use Docker Desktop instead, open the application, wait for the engine to report ready, run docker version, and recheck Maia.

After the status becomes Full automation

1. Return to the original Slack, Discord, or other gateway conversation.
2. Retry the same request. Maia replaces the affected execution environment at the next request boundary.
3. Do not add another file grant unless the response is a genuine path authorization denial.