Skip to main content

​
Installation

Get Maestro up and running on your platform of choice. Download pre-built binaries or build from source.

​
Download Pre-Built Binaries

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

macOS

DMG or ZIPAvailable for both Intel and Apple Silicon (M1/M2/M3)Choose the appropriate architecture:
  • maestro-{version}-arm64-mac.dmg (Apple Silicon)
  • maestro-{version}-x64-mac.dmg (Intel)

Windows

EXE Installer or Portable EXE
  • Maestro-Setup-{version}-x64.exe (Installer)
  • Maestro-Portable-{version}-x64.exe (No installation required)

Linux

AppImage, DEB, or RPM
  • maestro-{version}-x64.AppImage
  • maestro-{version}-amd64.deb
  • maestro-{version}-x86_64.rpm

​
Platform-Specific Installation

Using DMG:
  1. Download the appropriate .dmg file for your processor
  2. Open the DMG file
  3. Drag Maestro.app to your Applications folder
  4. Launch Maestro from Applications
Using ZIP:
  1. Download and extract the .zip file
  2. Move Maestro.app to Applications
  3. Launch from Applications
First launch may show a security warning. Go to System Settings → Privacy & Security and click “Open Anyway”.

​
Requirements

At least one supported AI coding agent must be installed and authenticated:
  • Claude Code - Anthropic’s AI coding assistant (fully integrated)
  • OpenAI Codex - OpenAI’s coding agent (fully integrated)
  • OpenCode - Open-source AI coding assistant (fully integrated)
  • Factory Droid - Factory’s AI coding assistant (fully integrated)
Optional:
  • Git (for git-aware features like diffs, logs, and worktrees)
Maestro is a pass-through to your provider. Your MCP tools, custom skills, permissions, and authentication all work in Maestro exactly as they do when running the provider directly—Maestro just orchestrates the conversation flow in batch mode.

​
Upgrading Maestro

Upgrading is simple:
  1. Download the new version
  2. Replace the old binary with the new one
  3. Launch Maestro
All your data persists across upgrades:
  • Sessions and conversation history
  • Settings and preferences
  • Playbooks and Auto Run documents
  • Custom themes and keyboard shortcuts
Configuration is stored in:
  • macOS: ~/Library/Application Support/maestro/
  • Windows: %APPDATA%\maestro\
  • Linux: ~/.config/maestro/

​
Building from Source

Prefer to build Maestro yourself? You’ll need Node.js 22.0.0 or higher.
1

Verify Node.js version

node --version  # Should be v22.0.0 or higher
If you need to install Node.js, visit nodejs.org.
2

Clone the repository

git clone https://github.com/RunMaestro/Maestro.git
cd Maestro
3

Install dependencies

npm install
This will also rebuild native modules (node-pty, better-sqlite3) for your platform.
4

Run in development mode

npm run dev
This starts Maestro with hot reload. The app will use an isolated data directory (maestro-dev/) so you can run it alongside a production install.
5

Build for production (optional)

# Build all components
npm run build

# Package for your platform
npm run package        # All platforms
npm run package:mac    # macOS only
npm run package:win    # Windows only  
npm run package:linux  # Linux only
Built packages will be in the release/ directory.
Building from source requires native module compilation:
  • Windows: Visual Studio Build Tools
  • macOS: Xcode Command Line Tools (xcode-select --install)
  • Linux: build-essential package (usually pre-installed)

​
WSL2 Users (Windows Subsystem for Linux)

When using 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 critical issues:
IssueSymptom
Socket binding failuresEPERM: operation not permitted when starting dev server
Electron sandbox crashesFATAL:sandbox_host_linux.cc errors
npm install failuresTimeouts, ENOTEMPTY rename errors
Git corruptionMissing index files, spurious lock files
# Clone to Linux filesystem (not /mnt/...)
cd ~
git clone https://github.com/RunMaestro/Maestro.git
cd Maestro

# Install dependencies
npm install

# Run in development mode
npm run dev

​
Accessing Files from Windows

Browse your WSL2 files from Windows Explorer: 
\\wsl$\Ubuntu\home\<username>\Maestro

​
Troubleshooting WSL2

If you encounter electron-rebuild failures, set the temp directory: 
TMPDIR=/tmp npm install

​
Next Steps

Quick Start

Get from installation to your first productive session

Features Overview

Explore all the power features and capabilities

Build docs developers (and LLMs) love

Get started for freeTalk to us