Install Maestro

Install from npm

Install is the one-time setup. Once maestro is on your PATH, you can start a local loop in any repo and come back to the same control surface when work is in flight.

If you are on a supported platform, the published npm package is the fastest path to install or upgrade:

npm install -g @olhapi/maestro

The installed command name is still maestro.

Add the MCP server to Codex

Once maestro is on your PATH, register the shipped MCP bridge with Codex:

codex mcp add maestro -- maestro mcp

If you built Maestro from source and the binary is not on your PATH, replace maestro with the absolute path to the binary you built.

Official npm builds currently cover:

• macOS arm64
• macOS x64
• Linux x64 (glibc)
• Linux arm64 (glibc)
• Windows x64

Linux npm packages target glibc only. Alpine and other musl-based distros should build from source or use Docker.

Docker image

Use the published GHCR image when you want a containerized install path:

docker pull ghcr.io/olhapi/maestro:latest

The image entrypoint is maestro. Its default command is run --db /data/maestro.db, so mounting only a data directory is enough to start the shared daemon with the container defaults.

Build from source

For local development or unsupported platforms, build the binary directly from the repo:

go build -o maestro ./cmd/maestro

Contributor Docker build:

docker build -t maestro-local .

What to install first

• Install go if you need source builds or local development.
• Install codex before you attempt real orchestration runs that launch the Codex CLI.
• Use the npm package when you want the shortest path from machine setup to codex mcp add maestro -- maestro mcp.

Contributor tooling

If you are contributing from a repo checkout, run the root install once before anything else:

pnpm install

That single install does three things:

• installs the repo-managed Git hooks through Husky
• bootstraps the shared workspace across apps/frontend and apps/website
• makes the root helper scripts available for common docs-site tasks

If you contribute regularly across multiple machines or rely on CI often, you can also enable Turborepo Remote Cache locally with:

pnpm exec turbo login && pnpm exec turbo link

For website work, the most useful root commands are:

• pnpm verify for the full local verification suite before pushing
• pnpm run verify:pre-push for the exact pre-push hook suite, including current-host npm smoke and retry-safety coverage
• pnpm run website:dev for the local Astro docs server
• pnpm run website:check for type and content validation
• pnpm run website:test for the website test suite
• pnpm run website:build for a production build check

The hooks stay targeted. Frontend changes run frontend lint and tests, website changes run Astro checks and website tests, workspace and hook changes run the full pnpm verify suite, and pre-push runs pnpm run verify:pre-push before the push proceeds with current-host npm smoke and the retry-safety harness included.

Next step

Once the binary is available on your machine, move to quickstart and create the first local workflow file.