Maestro/docs/installation.md

title, description, icon

title	description	icon
Installation	Download and install Maestro on macOS, Windows, or Linux.	download

Download

Download the latest release for your platform from the Releases page:

• macOS: .dmg or .zip (available for both Intel and Apple Silicon)
• Windows: .exe installer or portable .exe (no installation required)
• Linux: .AppImage, .deb, or .rpm (available for both x86_64 and arm64)
• Upgrading: Simply replace the old binary with the new one. All your data (sessions, settings, playbooks, history) persists in your config directory.

Requirements

• At least one supported AI coding agent installed and authenticated:
  • Claude Code — Anthropic's AI coding assistant (fully integrated)
  • Codex — OpenAI's coding agent (fully integrated)
  • OpenCode — Open-source AI coding assistant (fully integrated)
  • Aider, Gemini CLI, Qwen3 Coder — Planned support
• Git (optional, for git-aware features)

WSL2 Users (Windows Subsystem for Linux)

When developing or running Maestro with WSL2, always clone and run from the **native Linux filesystem** (e.g., `/home/username/maestro`), NOT from Windows-mounted paths (`/mnt/c/...`, `/mnt/d/...`).

Using Windows mounts causes several critical issues:

Issue	Symptom
Socket binding failures	EPERM: operation not permitted when starting dev server
Electron sandbox crashes	FATAL:sandbox_host_linux.cc errors
npm install failures	Timeouts, ENOTEMPTY rename errors
Git corruption	Missing index files, spurious lock files

Recommended WSL2 Setup

# Clone to Linux filesystem (not /mnt/...)
cd ~
git clone https://github.com/pedramamini/maestro.git
cd maestro

# Install dependencies
npm install

# Run in development mode
npm run dev

Accessing Files from Windows

You can browse your WSL2 files from Windows Explorer using:

\\wsl$\Ubuntu\home\<username>\maestro

Troubleshooting WSL2

If you encounter electron-rebuild failures, try setting the temp directory:

TMPDIR=/tmp npm run rebuild

For persistent issues, see Troubleshooting for additional WSL-specific guidance.

Building from Source

If you prefer to build Maestro from source:

# Prerequisites: Node.js 22.0.0 or higher
node --version  # Verify version

# Clone the repository
git clone https://github.com/pedramamini/maestro.git
cd maestro

# Install dependencies
npm install

# Run in development mode
npm run dev

# Or build for production
npm run build
npm run package

Building from source requires native module compilation (node-pty, better-sqlite3). On Windows, you'll need the [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/). On macOS, you'll need Xcode Command Line Tools (`xcode-select --install`).