maestro

README

Maestro - Multi-Container Claude

Run multiple isolated Claude Code instances in parallel (or other AI agents), each in their own Docker container with automatic branch management, network firewalls, and full development environment.

What is Maestro?

Maestro lets you work on multiple tasks simultaneously with Claude Code. Each task runs in its own isolated Docker container with:

• 🌳 Automatic git branches - Maestro creates appropriately named branches for each task
• 🔥 Network firewall - Containers can only access whitelisted domains
• 📦 Complete isolation - Full copy of your project in each container
• 🔔 Activity monitoring - See which tasks need your attention
• 🤖 Background daemon - Auto-monitors token expiration and sends notifications
• ♻️ Persistent state - npm/UV caches and command history survive restarts

Quick Install

curl -fsSL https://raw.githubusercontent.com/uprockcom/maestro/main/install.sh | bash

Prerequisites: Docker must be installed and running.

This installs the maestro binary and pulls the Docker image.

Build from Source

git clone https://github.com/uprockcom/maestro.git
cd maestro
make all              # Build binary + Docker image
sudo make install     # Install to /usr/local/bin

Windows

iew -ExecutionPolicy Bypass -Uri https://raw.githubusercontent.com/uprockcom/maestro/main/install.ps1 | iex

Note: Windows installs and runs natively, but Docker Desktop is still required, and it is not tested as thoroughly as macOS/Linux.

Getting Started

For the first run, you can just run maestro to start our interactive text UI, which will guide you through authentication and creating your first container. Alternatively, you can execute each step manually as follows:

1. Authenticate

Run once to set up Claude Code authentication:

maestro auth

This stores credentials in ~/.maestro/ and shares them (read-only) with all containers.

2. Configure (Optional)

Edit ~/.maestro/config.yml to customize your setup:

firewall:
  allowed_domains:
    - github.com
    - api.anthropic.com
    # Add your domains here
  # For corporate networks with internal DNS (Zscaler, VPN, etc.)
  internal_dns: "10.0.0.1"
  internal_domains:
    - "internal.company.com"

sync:
  additional_folders:
    - ~/Documents/Code/mcp-servers
    - ~/Documents/Code/helpers
  # Compression: gzip the tar stream when copying files to containers
  # - true (default): smaller transfer, good for remote Docker or slow I/O
  # - false: faster for large local projects (8GB+), skips compression overhead
  compress: false

# Git user for commits inside containers
git:
  user_name: "Your Name"
  user_email: "you@example.com"

# SSH agent forwarding for git authentication (keys stay on host)
ssh:
  enabled: true
  known_hosts_path: "~/.ssh/known_hosts"  # mount host's known_hosts to avoid prompts

# GitHub CLI integration (for PRs, issues, etc.)
github:
  enabled: true
  hostname: "github.mycompany.com"  # For GitHub Enterprise (omit for github.com)

# AWS Bedrock support (alternative to Anthropic API)
aws:
  enabled: true
  profile: "your-aws-profile"
  region: "us-east-1"

bedrock:
  enabled: true
  model: "anthropic.claude-sonnet-4-20250514-v1:0"

# SSL certificates for corporate HTTPS inspection
ssl:
  certificates_path: "~/.maestro/certificates"

# Android SDK for mobile development
android:
  sdk_path: "~/Android/Sdk"

# Container defaults
containers:
  default_return_to_tui: true  # Auto-check "Return to TUI" when creating containers

# Daemon and notification settings
daemon:
  check_interval: "10s"  # How often to check containers (default: 30m)
  notifications:
    enabled: true
    attention_threshold: "5s"  # Notify after this duration of waiting
    notify_on:
      - attention_needed  # When Claude waits for input
      - token_expiring    # When auth token is expiring

You can also set firewall rules from the text UI using the f shortcut.

AWS Bedrock Setup

To use Claude via AWS Bedrock instead of the Anthropic API:

1. Configure your AWS profile with Bedrock access
2. Enable bedrock in config (see above)
3. Run maestro auth to set up AWS SSO login
4. Containers will automatically use Bedrock for Claude

Corporate Network / VPN Setup

If you're behind a corporate proxy (Zscaler, etc.) or need to access internal resources:

1. Set firewall.internal_dns to your internal DNS server
2. Add internal domains to firewall.internal_domains
3. Host SSL certificates are automatically mounted for HTTPS inspection

SSL Certificates

For corporate environments with HTTPS inspection (Zscaler, etc.), place your CA certificates in the configured path:

1. Create the certificates directory: mkdir -p ~/.maestro/certificates
2. Copy your corporate CA certificates (.crt, .pem files) to this directory
3. Certificates are automatically imported into both the system trust store and Java keystore inside containers

Android SDK

For Android/mobile development, mount your host Android SDK into containers:

1. Set android.sdk_path to your SDK location (e.g., ~/Android/Sdk)
2. The SDK will be mounted read-only at /opt/android-sdk inside containers
3. Environment variables (ANDROID_HOME, ANDROID_SDK_ROOT) are automatically configured

Project-Level Exclusions (.maestroignore)

Create a .maestroignore file in your project root to exclude files/directories when copying to containers. This is useful for large projects with build artifacts that shouldn't be transferred.

# .maestroignore - exclude patterns (like .gitignore)
# Comments start with #

# Android/Gradle build artifacts
build
.gradle
.idea
.cxx
.kotlin

# Other common exclusions
dist
target
__pycache__
*.log

Notes:

• node_modules and .git are always excluded by default
• Each line is passed to tar --exclude=
• Empty lines and lines starting with # are ignored

3. Create Your First Container

maestro new "implement OAuth authentication"

Maestro will:

1. Generate an appropriate branch name (e.g., feat/oauth-auth)
2. Create an isolated container with your project
3. Start Claude in planning mode
4. Connect you to the container automatically

Note: After connecting, wait for a moment, and maestro will automatically input a prompt derived from your task description and hit enter to start claude.

Basic Usage

# Create a new container for a task
maestro new "fix API bug in users endpoint"
maestro new -f specs/design.md

# List all containers with status
maestro list

# Connect to a container
maestro connect feat-oauth-1

# Stop a container
maestro stop feat-oauth-1

# Clean up stopped containers
maestro cleanup

Inside a Container

When connected via maestro connect:

• Window 0: Claude Code (auto-approve mode)
• Window 1: Shell for manual commands
• Switch windows: Ctrl+b 0 or Ctrl+b 1
• Detach: Ctrl+b d (container keeps running)

Background Daemon

Note: Not tested on Windows.

The daemon monitors containers and sends desktop notifications when Claude needs your attention. It auto-starts when you launch the TUI (maestro), but you can also manage it manually:

maestro daemon start   # Start manually
maestro daemon stop    # Stop the daemon
maestro daemon status  # Check status
maestro daemon logs    # View logs

The daemon monitors:

• Attention needs - Notifies when Claude is waiting for input (configurable delay)
• Token expiration - Warns when auth token is expiring soon
• Container health - Periodic checks based on check_interval

Configure notification speed in ~/.maestro/config.yml:

daemon:
  check_interval: "10s"        # Check every 10 seconds (default: 30m)
  notifications:
    attention_threshold: "5s"  # Notify after 5s of waiting

Container Status

The maestro list command shows comprehensive status:

NAME              STATUS   BRANCH         GIT      ACTIVITY  AUTH
----              ------   ------         ---      --------  ----
feat-oauth-1      running  feat/oauth     Δ23 ↑2   2m ago    ✓ 147h    🔔
fix-api-bug-1     running  fix/api-bug    ✓        5m ago    ⚠ 2h
refactor-db-1     stopped  refactor/db    Δ5       12h ago   ✗ EXPIRED

Indicators:

• GIT: Δ23 = 23 changes, ↑2 = 2 commits ahead, ↓1 = 1 behind, ✓ = clean
• AUTH: ✓ valid, ⚠ expiring soon (< 24h), ✗ expired
• 🔔: Container needs attention
• 💤: Dormant (Claude exited)

Token Management

Claude tokens expire after 8 hours. Whichever session next connects will get the refresh and the others will all get auth errors. Maestro makes this easy:

# Check token status for all containers
maestro list

# Refresh tokens (copies freshest token from any active containers)
maestro refresh-tokens

# Re-authenticate if all tokens expired
maestro auth

The daemon automatically warns you about expiring tokens and supports auto-refresh.

Network Firewall

By default, containers can only access whitelisted domains from your config. To temporarily add a domain:

maestro add-domain feat-oauth-1 api.example.com

Maestro will offer to save it permanently to your config.

Documentation

• Complete Usage Guide - Detailed documentation, configuration, troubleshooting
• Architecture Details - Container structure, volumes, authentication
• Development Guide - Building, testing, modifying Maestro

Requirements

• Docker - Must be running (install)
• Claude Code - Authentication via maestro auth
• Go 1.25+ - Only needed if building from source

About

Maestro is built by UpRock, powering distributed uptime monitoring and next gen AI crawling. Run your agents with Maestro, ship faster, and verify every deploy doesn't break production with a single Uptime prompt on millions of real devices worldwide.

License

Apache 2.0 - See LICENSE file for details.