Windows Installation Guide

AI Maestro runs on Windows through WSL2 (Windows Subsystem for Linux), Microsoft's official solution for running Linux tools on Windows. This gives you the full power of tmux and Linux shell commands while still using your Windows browser and applications.

Why WSL2?

AI Maestro is built on tmux, a powerful terminal multiplexer that has no native Windows equivalent. Rather than building a limited Windows port, we leverage WSL2 to give you the complete, battle-tested Linux experience - the same one macOS and Linux users enjoy.

Benefits of WSL2:

Full tmux support with all features
Native Linux shell environment (bash, zsh)
Seamless integration with Windows (access Windows files, use Windows browser)
Used by millions of developers worldwide
Microsoft's official recommendation for Linux development on Windows
No dual-boot or virtual machine needed

Prerequisites

Windows 10 version 2004+ (Build 19041+) or Windows 11
Administrator access (for WSL2 installation)
8GB+ RAM recommended (4GB minimum)
5GB free disk space for WSL2 + AI Maestro

Installation Steps

Step 1: Install WSL2

Option A: Automatic Installation (Recommended - Windows 11 or Windows 10 2004+)

Open PowerShell as Administrator and run:

wsl --install

This single command:

Enables WSL and Virtual Machine Platform
Downloads and installs Ubuntu (default distribution)
Sets WSL2 as the default version
Configures everything automatically

After installation completes:

Restart your computer (required)
Ubuntu will launch automatically on first boot
Create a username and password when prompted (this is your Linux user - remember it!)

Option B: Manual Installation (if automatic fails)

If wsl --install doesn't work, follow Microsoft's detailed guide: https://docs.microsoft.com/en-us/windows/wsl/install-manual

Step 2: Verify WSL2 Installation

Open PowerShell (no admin needed) and run:

wsl --list --verbose

Expected output:

  NAME                   STATE           VERSION
* Ubuntu                 Running         2

The VERSION column must show 2. If it shows 1, upgrade to WSL2:

wsl --set-version Ubuntu 2

Step 3: Update Ubuntu and Install Prerequisites

Launch Ubuntu from the Start Menu (or type wsl in PowerShell). Run these commands:

# Update package list
sudo apt update

# Install required packages
sudo apt install -y curl git tmux build-essential

# Verify tmux installation
tmux -V
# Should show: tmux 3.x or higher

Step 4: Install Node.js and Yarn

Using nvm (Node Version Manager - Recommended):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Load nvm (or restart your terminal)
source ~/.bashrc

# Install Node.js 20 (LTS)
nvm install 20
nvm use 20

# Verify installation
node --version  # Should show v20.x.x
npm --version   # Should show 10.x.x

# Install Yarn globally
npm install -g yarn

# Verify Yarn
yarn --version  # Should show 1.22.x

Step 5: Install AI Maestro

Option A: Automatic Installation (Easiest)

# Run the official installer
curl -fsSL https://raw.githubusercontent.com/23blocks-OS/ai-maestro/main/scripts/remote-install.sh | sh

Unattended installation (skips all prompts):

curl -fsSL https://raw.githubusercontent.com/23blocks-OS/ai-maestro/main/scripts/remote-install.sh | sh -s -- -y --auto-start

The installer will:

Detect WSL2 environment
Clone the repository
Install dependencies
Configure tmux
Set up SSH agent (for git operations)

Option B: Manual Installation

# Clone the repository
cd ~
git clone https://github.com/23blocks-OS/ai-maestro.git
cd ai-maestro

# Install dependencies
yarn install

# Configure tmux for optimal scrolling
./scripts/setup-tmux.sh

# Configure SSH agent (CRITICAL for git operations)
cat << 'EOF' >> ~/.tmux.conf

# SSH Agent Configuration - AI Maestro
set-option -g update-environment "DISPLAY SSH_ASKPASS SSH_AGENT_PID SSH_CONNECTION WINDOWID XAUTHORITY"
set-environment -g 'SSH_AUTH_SOCK' ~/.ssh/ssh_auth_sock
EOF

cat << 'EOF' >> ~/.bashrc

# SSH Agent for tmux - AI Maestro
if [ -S "$SSH_AUTH_SOCK" ] && [ ! -h "$SSH_AUTH_SOCK" ]; then
    mkdir -p ~/.ssh
    ln -sf "$SSH_AUTH_SOCK" ~/.ssh/ssh_auth_sock
fi
EOF

# Apply SSH configuration
source ~/.bashrc
mkdir -p ~/.ssh && ln -sf "$SSH_AUTH_SOCK" ~/.ssh/ssh_auth_sock 2>/dev/null
tmux source-file ~/.tmux.conf 2>/dev/null || true

Step 6: Start AI Maestro

cd ~/ai-maestro
yarn dev

Expected output:

> Ready on http://0.0.0.0:23000

Step 7: Access from Windows Browser

AI Maestro is now running in WSL2, but you can access it from your Windows browser:

Open your browser (Chrome, Edge, Firefox) and navigate to:

http://localhost:23000

That's it! You should see the AI Maestro dashboard.

Understanding WSL2 File System

WSL2 has its own Linux file system, separate from your Windows files. Here's how they interact:

Accessing Windows Files from WSL2

Your Windows drives are mounted at /mnt/:

# Access C:\ drive
cd /mnt/c/Users/YourUsername/Documents

# Access D:\ drive
cd /mnt/d/

Example: Clone a repo from Windows Documents folder:

cd /mnt/c/Users/YourUsername/Documents
git clone https://github.com/your/project.git
cd project
tmux new-session -s myproject-dev

Accessing WSL2 Files from Windows

Open Windows File Explorer and type in the address bar:

\\wsl$\Ubuntu\home\your-linux-username

Or navigate to: Network > \wsl$\Ubuntu

Example paths:

AI Maestro code: \\wsl$\Ubuntu\home\your-username\ai-maestro
Session logs: \\wsl$\Ubuntu\home\your-username\ai-maestro\logs

Pro tip: Pin this location to Quick Access in File Explorer for easy access.

Network Access Configuration

By default, AI Maestro binds to 0.0.0.0:23000, making it accessible:

✅ From Windows: http://localhost:23000
✅ From other devices on your network: http://YOUR-PC-IP:23000

Localhost-Only Mode (More Secure)

If you want to restrict access to only your Windows machine:

# Create .env.local in the ai-maestro directory
cd ~/ai-maestro
cat << 'EOF' > .env.local
HOSTNAME=localhost
PORT=23000
EOF

# Restart AI Maestro
yarn dev

Auto-Start Configuration (Optional)

To have AI Maestro start automatically when you open WSL2:

Option 1: Add to ~/.bashrc

echo '
# Auto-start AI Maestro dashboard (optional)
if ! pgrep -f "node.*server.mjs" > /dev/null; then
    cd ~/ai-maestro && yarn dev &
    echo "AI Maestro started at http://localhost:23000"
fi
' >> ~/.bashrc

Option 2: Use pm2 (Process Manager)

# Install pm2
npm install -g pm2

# Start AI Maestro with pm2
cd ~/ai-maestro
pm2 start yarn --name "ai-maestro" -- dev

# Save pm2 configuration
pm2 save

# Set pm2 to start on WSL2 launch
pm2 startup
# Follow the instructions shown

# View status
pm2 status
pm2 logs ai-maestro

pm2 commands:

pm2 stop ai-maestro      # Stop the dashboard
pm2 restart ai-maestro   # Restart the dashboard
pm2 logs ai-maestro      # View logs
pm2 delete ai-maestro    # Remove from pm2

Common WSL2 Issues and Solutions

Issue 1: "wsl --install" command not found

Cause: You're running an older version of Windows 10.

Solution:

Update Windows to version 2004 or later (Settings > Update & Security > Windows Update)
Use the manual installation method: Microsoft's WSL Manual Install Guide

Issue 2: WSL2 is running as WSL1

Symptoms:

wsl --list --verbose
# Shows VERSION 1 instead of 2

Solution:

# In PowerShell as Administrator
wsl --set-default-version 2
wsl --set-version Ubuntu 2

Issue 3: Port 23000 already in use

Symptoms:

Error: listen EADDRINUSE: address already in use :::23000

Solution:

# Check what's using port 23000
lsof -i :23000

# Kill the process
kill -9 <PID>

# Or use a different port
PORT=3000 yarn dev

Issue 4: Can't access localhost:23000 from Windows browser

Cause: Windows firewall blocking WSL2 network access.

Solution:

Option A: Allow through Windows Firewall

Open Windows Security > Firewall & network protection
Click "Allow an app through firewall"
Add Node.js to allowed apps for Private networks

Option B: Temporarily disable firewall (testing only)

Windows Security > Firewall & network protection
Turn off for Private network (re-enable after testing)

Option C: Use explicit IP

# In WSL2, get your WSL2 IP
ip addr show eth0 | grep inet | awk '{print $2}' | cut -d/ -f1

# Use that IP in Windows browser
http://172.x.x.x:23000

Issue 5: tmux sessions not persisting after WSL2 restart

Cause: WSL2 shuts down when no processes are running.

Solution:

# Option 1: Use tmux detach instead of exiting WSL2
# In tmux: Ctrl+B then D (detach)
# Sessions persist as long as WSL2 is running

# Option 2: Keep WSL2 running
# In PowerShell, this keeps WSL2 alive:
wsl --exec tail -f /dev/null

Note: tmux sessions are NOT persistent across WSL2 VM restarts. This is expected behavior.

Issue 6: Git SSH keys not working in tmux sessions

Symptoms:

Permission denied (publickey)
git@github.com: Permission denied (publickey)

Cause: SSH agent not configured for tmux.

Solution:

Already included in Step 5, but verify:

# Check if SSH agent configuration exists
grep -A2 "SSH_AUTH_SOCK" ~/.tmux.conf
grep -A5 "SSH_AUTH_SOCK" ~/.bashrc

# If missing, add it
cat << 'EOF' >> ~/.tmux.conf

# SSH Agent Configuration - AI Maestro
set-option -g update-environment "DISPLAY SSH_ASKPASS SSH_AGENT_PID SSH_CONNECTION WINDOWID XAUTHORITY"
set-environment -g 'SSH_AUTH_SOCK' ~/.ssh/ssh_auth_sock
EOF

cat << 'EOF' >> ~/.bashrc

# SSH Agent for tmux - AI Maestro
if [ -S "$SSH_AUTH_SOCK" ] && [ ! -h "$SSH_AUTH_SOCK" ]; then
    mkdir -p ~/.ssh
    ln -sf "$SSH_AUTH_SOCK" ~/.ssh/ssh_auth_sock
fi
EOF

# Apply configuration
source ~/.bashrc
mkdir -p ~/.ssh && ln -sf "$SSH_AUTH_SOCK" ~/.ssh/ssh_auth_sock
tmux source-file ~/.tmux.conf

# Test SSH key
ssh -T git@github.com

Issue 7: High memory usage

Symptoms: WSL2 consuming too much RAM.

Solution:

Create .wslconfig in your Windows user directory (C:\Users\YourUsername\.wslconfig):

[wsl2]
memory=4GB
processors=2
swap=2GB

Restart WSL2:

wsl --shutdown
wsl

Issue 8: Slow file system performance

Cause: Working with files on Windows drives (/mnt/c/) instead of WSL2's native file system.

Solution:

Always work in WSL2's native file system for best performance:

# ❌ SLOW - Working on Windows drive
cd /mnt/c/Users/YourName/Documents/my-project

# ✅ FAST - Working in WSL2 home directory
cd ~/my-project

Move project to WSL2:

# Copy from Windows to WSL2
cp -r /mnt/c/Users/YourName/Documents/my-project ~/my-project

# Or clone fresh in WSL2
cd ~
git clone https://github.com/your/project.git

Issue 9: WSL2 IP changes after restart

Symptoms: Mobile access URL stops working after restarting Windows.

Cause: WSL2 gets a new IP address on each restart.

Solution:

Option 1: Always use localhost (recommended for local access)

http://localhost:23000

Option 2: Get current IP dynamically

# In WSL2, run this to get current IP
ip addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}'

# Or create a helper script
cat << 'EOF' > ~/ai-maestro/get-ip.sh
#!/bin/bash
IP=$(ip addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}')
echo "Access AI Maestro at: http://$IP:23000"
EOF
chmod +x ~/ai-maestro/get-ip.sh

# Run it
~/ai-maestro/get-ip.sh

Option 3: Use Tailscale for stable remote access

See the main README's Mobile Access section for Tailscale setup.

Performance Tips

1. Use WSL2's Native File System

Always work in ~/ instead of /mnt/c/:

# ❌ Slow - Cross-boundary access
cd /mnt/c/Users/YourName/projects

# ✅ Fast - Native WSL2
cd ~/projects

2. Increase WSL2 Resources

Edit C:\Users\YourUsername\.wslconfig:

[wsl2]
memory=8GB           # Increase for large projects
processors=4         # Match your CPU cores
swap=4GB
localhostForwarding=true

3. Disable Windows Defender Scanning for WSL2

Windows Defender scanning WSL2 files can slow things down:

Open Windows Security
Virus & threat protection > Manage settings
Exclusions > Add an exclusion
Add folder: %USERPROFILE%\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu_*\LocalState\ext4.vhdx

Warning: Only do this if you trust all code in your WSL2 environment.

Uninstalling

Remove AI Maestro

# In WSL2
cd ~
rm -rf ai-maestro

# If using pm2
pm2 delete ai-maestro
pm2 save

Remove WSL2 (Optional)

In PowerShell as Administrator:

# Unregister Ubuntu
wsl --unregister Ubuntu

# Disable WSL features
dism.exe /online /disable-feature /featurename:Microsoft-Windows-Subsystem-Linux /norestart
dism.exe /online /disable-feature /featurename:VirtualMachinePlatform /norestart

# Restart computer

Additional Resources

Official Documentation

AI Maestro Documentation

Community Support

Tips for Windows Developers

1. Use Windows Terminal

Windows Terminal is Microsoft's modern terminal:

Beautiful UI
Tabs support
Split panes
Better rendering than cmd.exe

Install from Microsoft Store or:

winget install Microsoft.WindowsTerminal

2. Configure Windows Terminal for WSL2

Add a custom profile in Windows Terminal settings:

{
  "name": "AI Maestro",
  "commandline": "wsl -d Ubuntu -- bash -c 'cd ~/ai-maestro && bash'",
  "startingDirectory": "//wsl$/Ubuntu/home/your-username/ai-maestro"
}

3. Git Configuration

Your Windows Git and WSL2 Git are separate. Configure both:

# In WSL2
git config --global user.name "Your Name"
git config --global user.email "your@email.com"

# Use your Windows SSH keys in WSL2
ln -s /mnt/c/Users/YourUsername/.ssh ~/.ssh

4. VS Code Integration

VS Code has excellent WSL2 support:

# Install VS Code on Windows, then in WSL2:
code ~/ai-maestro

# VS Code will install WSL extension automatically

5. Clipboard Integration

Copy/paste works seamlessly between Windows and WSL2:

# Copy to Windows clipboard from WSL2
echo "Hello from WSL2" | clip.exe

# Paste in WSL2 from Windows clipboard
powershell.exe Get-Clipboard

FAQ

Q: Do I need to install anything on Windows besides WSL2?

A: No. All development tools (Node.js, yarn, tmux, AI Maestro) are installed inside WSL2. You only access the web dashboard from your Windows browser.

Q: Can I use my existing WSL2 installation?

A: Yes! Just install Node.js, yarn, and tmux inside your existing WSL2 distribution, then follow the AI Maestro installation steps.

Q: Will this affect my Windows performance?

A: WSL2 uses about 2-4GB of RAM when running. If you have 8GB+ RAM, you won't notice any slowdown.

Q: Can I access Windows files from AI Maestro agents?

A: Yes! All Windows drives are mounted at /mnt/c/, /mnt/d/, etc. You can create tmux sessions anywhere:

cd /mnt/c/Users/YourName/Documents/my-project
tmux new-session -s my-project

Q: Do tmux sessions persist after closing Windows Terminal?

A: Yes! tmux sessions run in WSL2's background. Close Windows Terminal, reopen it, and your sessions are still there. However, sessions are lost if WSL2 shuts down (when no processes running) or if you restart Windows.

Q: Can I use this with Claude Code / Aider / Cursor?

A: Absolutely! Install your AI agent inside WSL2:

# Example: Claude Code
# Download and install according to their docs

# Create an agent
tmux new-session -s claude-backend
claude

# Detach: Ctrl+B then D
# View in AI Maestro dashboard

Q: Is WSL2 slower than native Linux?

A: WSL2 file system performance is near-native Linux speed (within 5-10%). Network performance is identical. For terminal-based development, you won't notice any difference.

Q: Can I run multiple Linux distributions?

A: Yes! You can install Ubuntu, Debian, Fedora, etc., and run AI Maestro in any of them.

Q: What if I already have tmux sessions from before installing AI Maestro?

A: They'll appear as agents in the dashboard automatically! AI Maestro auto-discovers all tmux sessions.

Q: How do I update AI Maestro?

cd ~/ai-maestro
git pull origin main
yarn install
# Restart the dashboard (Ctrl+C, then yarn dev)

Support

If you run into issues not covered here:

Check TROUBLESHOOTING.md
Search existing GitHub issues
Open a new issue with:
- Windows version (winver in Run dialog)
- WSL2 version (wsl --list --verbose in PowerShell)
- Error messages
- Steps to reproduce

Made with ♥ in Boulder, Colorado

Built for developers who love AI pair programming on Windows

FilesExpand file tree

WINDOWS-INSTALLATION.md

Latest commit

History

WINDOWS-INSTALLATION.md

File metadata and controls

Windows Installation Guide

Why WSL2?

Prerequisites

Installation Steps

Step 1: Install WSL2

Step 2: Verify WSL2 Installation

Step 3: Update Ubuntu and Install Prerequisites

Step 4: Install Node.js and Yarn

Step 5: Install AI Maestro

Step 6: Start AI Maestro

Step 7: Access from Windows Browser

Understanding WSL2 File System

Accessing Windows Files from WSL2

Accessing WSL2 Files from Windows

Network Access Configuration

Localhost-Only Mode (More Secure)

Auto-Start Configuration (Optional)

Option 1: Add to ~/.bashrc

Option 2: Use pm2 (Process Manager)

Common WSL2 Issues and Solutions

Issue 1: "wsl --install" command not found

Issue 2: WSL2 is running as WSL1

Issue 3: Port 23000 already in use

Issue 4: Can't access localhost:23000 from Windows browser

Issue 5: tmux sessions not persisting after WSL2 restart

Issue 6: Git SSH keys not working in tmux sessions

Issue 7: High memory usage

Issue 8: Slow file system performance

Issue 9: WSL2 IP changes after restart

Performance Tips

1. Use WSL2's Native File System

2. Increase WSL2 Resources

3. Disable Windows Defender Scanning for WSL2

Uninstalling

Remove AI Maestro

Remove WSL2 (Optional)

Additional Resources

Official Documentation

AI Maestro Documentation

Community Support

Tips for Windows Developers

1. Use Windows Terminal

2. Configure Windows Terminal for WSL2

3. Git Configuration

4. VS Code Integration

5. Clipboard Integration

FAQ

Support