Installation

Fresh

SOP-INSTALL-001: Install Maestro

Field	Value
ID	SOP-INSTALL-001
Version	1.0
Status	Active

Decision Tree

Step 1: Download

Go to Maestro Releases and download the appropriate package:

Windows

• Installer: Maestro-Setup-x.x.x.exe — Standard Windows installer
• Portable: Maestro-Portable-x.x.x.exe — No installation needed, run from anywhere

macOS

• Apple Silicon: Maestro-x.x.x-arm64-mac.zip or Maestro-x.x.x-arm64.dmg
• Intel: Maestro-x.x.x-mac.zip or Maestro-x.x.x.dmg

Linux

• Universal: Maestro-x.x.x.AppImage (x86_64) or Maestro-x.x.x-arm64.AppImage
• Debian/Ubuntu: maestro_x.x.x_amd64.deb or maestro_x.x.x_arm64.deb
• Fedora/RHEL: maestro-x.x.x.x86_64.rpm or maestro-x.x.x.aarch64.rpm

Step 2: Install

Windows

# Run the installer
./Maestro-Setup-0.14.5.exe
# Or just double-click Maestro-Portable-0.14.5.exe

macOS

# DMG: Open, drag to Applications
open Maestro-0.14.5-arm64.dmg

# ZIP: Extract and move to Applications
unzip Maestro-0.14.5-arm64-mac.zip -d /Applications/

Linux - AppImage

chmod +x Maestro-0.14.5.AppImage
./Maestro-0.14.5.AppImage

Linux - Debian

sudo dpkg -i maestro_0.14.5_amd64.deb

Linux - RPM

sudo rpm -i maestro-0.14.5.x86_64.rpm

Step 3: Build from Source (Optional)

# Requirements: Node.js 22.0.0+
git clone https://github.com/RunMaestro/Maestro.git
cd Maestro
npm install
npm run dev        # Development mode
# OR
npm run build && npm run package  # Production build

Prerequisites

You need at least one supported AI agent installed and authenticated:

Agent	Install Command	Auth
Claude Code	npm install -g @anthropic-ai/claude-code	claude login
OpenAI Codex	npm install -g @openai/codex	Set OPENAI_API_KEY
OpenCode	npm install -g opencode	Configure provider

Optional but recommended:

• Git — For git-aware features and worktrees
• GitHub CLI (gh) — Required for PR creation, Gist sharing, and Symphony

WSL2 Warning

Always clone and run from the native Linux filesystem (/home/...), never from Windows-mounted paths (/mnt/c/...). Using Windows mounts causes:

• Socket binding failures
• Electron sandbox crashes
• npm install failures
• Git corruption

Verification Checklist

• [ ] Maestro launches without errors
• [ ] At least one AI provider is installed and authenticated
• [ ] Git is available (optional but recommended)
• [ ] GitHub CLI is available (optional for PRs/Symphony)

See Also

• First Launch Setup — Configure your first agent
• Provider Configuration — Detailed provider setup