MMaia Docs
Product overview
Get started

Install Maia

Install Maia on Linux, macOS, or Windows through WSL2.

Maia runs on Linux, macOS, and Windows through WSL2. The installer creates an isolated Maia home, installs the command-line application and dashboard, and starts the guided setup.

Before you begin

  • Use a normal user account with permission to install software in your home directory.
  • Confirm that the machine can reach GitHub and the model provider you plan to use.
  • On Windows, install WSL2 and run Maia inside Ubuntu. Native PowerShell is not the Maia runtime.
  • Decide whether this installation needs governed terminal/code and Office automation. Maia can be installed without Docker or Podman, but those capabilities remain in Restricted mode until a secure runtime is ready.

Run the quick installer

Run this command in a Linux, macOS, or WSL terminal:

curl -fsSL https://ampliia.com/maia/install.sh | bash

The installer checks the system, creates ~/.maia, clones Maia into ~/.maia/maia, provisions its Python environment, installs the dashboard frontend, creates initial configuration files, and makes the maia command available. It prefers ~/.local/bin for user commands and automatically falls back to ~/.maia/bin, including the shell PATH update, when the preferred directory is unavailable or not writable. It also checks Docker or Podman readiness, offers rootless Podman installation on supported Linux distributions, and otherwise completes safely in Restricted mode with exact next steps.

Inspect before running.

Open the installer source if your organization requires script review before execution.

Installer options

# Install without opening guided setup
curl -fsSL https://ampliia.com/maia/install.sh | bash -s -- --skip-setup

# Install a specific branch
curl -fsSL https://ampliia.com/maia/install.sh | bash -s -- --branch main

# Use a different Maia data directory
curl -fsSL https://ampliia.com/maia/install.sh | MAIA_HOME=/srv/maia-data bash

Install on Windows with WSL2

  1. Open PowerShell as Administrator and install Ubuntu:
    wsl --install -d Ubuntu
  2. Restart Windows if requested, then open the Ubuntu application.
  3. For full governed automation, install and start Docker Desktop. Open Settings → Resources → WSL Integration, enable Ubuntu, choose Apply & restart, and confirm inside Ubuntu that docker version shows both Client and Server.
  4. Run the quick installer inside Ubuntu:
    curl -fsSL https://ampliia.com/maia/install.sh | bash
  5. Reload your shell and start setup:
    source ~/.bashrc
maia setup
Keep the installation on the Linux filesystem.

Use ~/.maia, not a directory under /mnt/c. Linux filesystem paths avoid the performance and permission problems common to WSL-mounted Windows directories.

Install from a clone

Use this path when you need to review or modify the Maia source:

git clone https://github.com/and270/maia.git
cd maia
./setup-maia.sh

Verify the installation

maia status
maia doctor
maia secure-runtime status
Expected result. maia status finds the configuration and maia doctor reports no blocking dependency errors. The secure-runtime command reports either Full automation or a safe Restricted mode with operating-system steps.

See Enable full governed automation for the complete Windows/WSL, Linux, and macOS procedure and the consequences of leaving it unconfigured.

Continue with Complete the first run.

↑↓ navigateEsc close