Maestro/docs/installation.md at 5da418cf7fe3537bf75d1b19bda8565ea65ab61e

mirror of https://github.com/jlengrand/Maestro.git synced 2026-03-10 08:31:19 +00:00

Files

Pedram Amini 4d67cce6e1 ## CHANGES

- Enforced strict Node versioning with `.npmrc` engine-strict enabled ⚙️
- Declared Node.js >=20 requirement via `package.json` engines field 🚀
- Added early WSL2 environment checks during app startup 🕵️
- Introduced WSL detector utility to identify WSL and cache results 🧠
- Detects `/mnt/<drive>` Windows-mount paths to prevent common breakages 🧭
- Emits clear warnings for WSL mount risks: sockets, Electron, npm, git 🔥
- Added user-friendly WSL warning message with fix steps and docs link 📣
- Expanded installation docs with WSL2 best-practice cloning guidance 📘
- Added troubleshooting playbook for WSL2 errors and proven remedies 🛠️
- Polished File Explorer status bar styling with rounded bordered container 🎨

2025-12-30 04:14:24 -06:00

2.1 KiB

Raw Blame History

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
Windows: .exe installer
Linux: .AppImage, .deb, or .rpm
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
- OpenAI Codex - OpenAI's coding agent
- OpenCode - Open-source AI coding assistant
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

2.1 KiB Raw Blame History