Skip to content

Installation

Jump to bottom
rluisr edited this page Jul 23, 2026 · 2 revisions

Installation

English | 日本語

Get maestro running and complete one successful run. Read this page top-to-bottom once; later jumps are linked from Home.

Overview

Path When to use Time
A. Local Try on a laptop / disposable repo ~15 min
B. Container Shared host, staging, simple deploy ~20 min
C. Production shape Public HTTPS, MCP Gateway, OIDC longer
D. GCP Terraform Cloud Run + Global LB + IAP + self-hosted worker longer

All paths need the same three secrets:

  1. ANTHROPIC_API_KEY
  2. GITHUB_APP_ID
  3. GITHUB_APP_PRIVATE_KEY or GITHUB_APP_PRIVATE_KEY_PATH

There is no PAT mode. Authentication is GitHub App only.

1. Create a GitHub App

  1. GitHub → Settings → Developer settings → GitHub Apps → New GitHub App

  2. Set a name and any homepage URL (can be http://127.0.0.1:3000 for local)

  3. Webhook: leave inactive unless you later enable review webhooks

  4. Repository permissions (minimum):

    Permission Access
    Metadata Read-only
    Contents Read and write
    Issues Read and write
    Pull requests Read and write

  5. Create the app → note the App ID

  6. Generate a private key → download the .pem file

  7. Install App → choose the account/org → only the repositories maestro should touch

Optional later:

  • GITHUB_APP_INSTALLATION_ID — if omitted, maestro resolves the installation from owner/repo
  • Narrow installation to specific repos (recommended for production)

2. Anthropic API key

  1. Create an API key in the Claude / Anthropic console
  2. Confirm your org can use Claude Managed Agents (sessions, agents, vaults)
  3. Export as ANTHROPIC_API_KEY

Path A — Local development

Prerequisites

  • mise (recommended) or Bun 1.3.14 (see mise.toml)
  • Git, a terminal
  • The GitHub App PEM from step 1

Setup

git clone https://github.com/ca-srg/maestro.git
cd maestro
mise install          # installs pinned Bun
bun install
cp .env.example .env

Edit .env (minimum):

ANTHROPIC_API_KEY=sk-ant-...
GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY_PATH=/absolute/path/to/github-app.pem

Or paste the PEM inline (escape newlines as \n):

GITHUB_APP_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"

Start

bun run start
# → Listening on http://127.0.0.1:3000

Watch mode: bun run dev.

First run in the UI

  1. Open http://127.0.0.1:3000
  2. New run → repository owner/name + open issue number
    • You can also paste https://github.com/owner/name/issues/42
  3. Start the run
  4. Open the run detail page — events stream live
  5. When finished, open the PR URL from the run summary

Optional: auto-trigger from GitHub

  1. Dashboard → Repositories → add owner/name as a polled repository
  2. On an open issue, either:
    • add label agent-run (default; override with GITHUB_TRIGGER_LABEL), or
    • comment @bot run (default bot name; override with GITHUB_BOT_MENTION)

The poller always starts; with an empty repo list it is a no-op.

Optional: local MCP tunnel (Figma, etc.)

Managed Agents run in Anthropic’s cloud and cannot reach 127.0.0.1. For local stdio MCP servers:

ENABLE_DEV_TUNNEL=true
NGROK_AUTHTOKEN=...
MCP_GATEWAY_TOKEN=$(uuidgen)   # keep this value stable in .env

Requires pip install mcp-proxy and entries in mcp-proxy.json. Full detail: docs/DEVELOPMENT.md.

Path B — Container

Build

make docker-build VERSION=0.1.0
# or: docker build --platform=linux/amd64 -t maestro:0.1.0 .

Run

docker run --rm \
  -p 3000:3000 \
  -e ANTHROPIC_API_KEY \
  -e GITHUB_APP_ID \
  -e GITHUB_APP_PRIVATE_KEY_PATH=/secrets/github-app.pem \
  -v /path/to/github-app.pem:/secrets/github-app.pem:ro \
  -v maestro-data:/data \
  maestro:0.1.0

Image layout (from Dockerfile / scripts/start.sh):

Path Role
/app Application (read-only at runtime)
/data/app SQLite DB + agent state (DB_PATH default /data/app/dashboard.db)
/app/.maestro Symlink into agent state under /data
Ports 3000 App (loopback behind ingress when used)
Ports 8080 / 8096 / 8097 Ingress / mcp-proxy / mcp-gateway when sidecars enabled

Persist /data across restarts. SQLite is single-writer — run one maestro instance against a given DB volume.

Entrypoint variants

Command Use
./scripts/start.sh (default) App + optional MCP sidecars / ingress / Litestream
./scripts/start-mcp.sh MCP proxy + gateway only (split deploy)

Path C — Production shape

Not a single vendor recipe — a shape that matches how the container is built.

                    ┌─ app.example.com ──► ingress-proxy ──► maestro :3000
Internet ───────────┤
                    └─ mcp.example.com ──► ingress-proxy ──► mcp-gateway :8097
                                                              └─ mcp-proxy :8096
                                                                   └─ stdio MCPs

Recommended env (sketch)

ANTHROPIC_API_KEY=...
GITHUB_APP_ID=...
GITHUB_APP_PRIVATE_KEY_PATH=/data/secrets/github-app.pem

# Hostnames
INGRESS_APP_HOSTNAME=app.example.com
INGRESS_MCP_HOSTNAME=mcp.example.com
INGRESS_AUTH_MODE=load-balancer

# MCP gateway
MCP_GATEWAY_TOKEN=<long-random-stable>
# Optional tighten (default includes Anthropic Managed Agents egress):
# MCP_GATEWAY_ALLOWED_CLIENT_CIDRS=160.79.104.0/21

# Dashboard auth (optional; all-or-nothing)
# OIDC_ISSUER_URL=...
# OIDC_CLIENT_ID=...
# OIDC_CLIENT_SECRET=...
# OIDC_REDIRECT_URI=https://app.example.com/auth/callback
# OIDC_ADMIN_EMAILS=you@example.com

Register each MCP server in the WebUI (/mcp-servers) with:

  • URL — public Streamable HTTP endpoint, e.g. https://mcp.example.com/servers/figma/mcp
  • token_env_name — env var name holding the Bearer (often MCP_GATEWAY_TOKEN)

See MCP-Servers and Configuration.

Self-hosted sandboxes

To enqueue sessions onto your workers instead of Anthropic cloud environments:

ANTHROPIC_ENVIRONMENT_ID=env_...
  • Set this on the maestro app only (non-secret id)
  • Keep ANTHROPIC_ENVIRONMENT_KEY on the worker/poller only
  • Do not share a fixed VAULT_ID in self-hosted mode

Details: docs/self-hosted-sandboxes.md

Path D — GCP Terraform

Production deploy on Google Cloud using the modules in terraform/:

  • app — Cloud Run WebUI/API + Litestream
  • mcp-gateway — dedicated Cloud Run MCP surface
  • worker — self-hosted poller (Worker Pool) + session Job
  • edge — Global HTTPS LB, IAP, Cloud Armor, Certificate Manager
cd terraform/examples/complete
cp terraform.tfvars.example terraform.tfvars
# edit hostnames, images, VPC, IAP, anthropic_environment_id
terraform init && terraform apply
# then inject Secret Manager versions (containers are empty)

Full walkthrough (prerequisites, secret injection, DNS cutover, Litestream three-step revision updates): Terraform. Module variable tables: terraform/README.md.

Verify the install

Check How
Process up Log line with listen address / no immediate exit
Dashboard GET http://127.0.0.1:3000/ returns HTML
GitHub auth Start a run on a repo the App can access; preflight fails fast on missing permissions
Anthropic Invalid key → clear auth error at run start
End-to-end Small open issue → PR opens → run status completed

Contributor verification (not required for operators):

bun run lint && bun run typecheck && bun test

Next

maestro

日本語

Repository · Issues

Clone this wiki locally