Installation and configuration
This page takes you from nothing installed to a working setup: the mso CLI, a configured
workspace in your project, and (on Team or Enterprise) the Maestro Hub dashboard.
You'll need about 15 minutes. The steps, in order:
- Check the prerequisites
- Install the package
- Activate a licence (paid tiers only)
- Create a workspace with
mso init - Run the setup wizard with
mso setup - Set your repository details
- Set up the Hub with
mso hub setup(Team / Enterprise)
1. Prerequisites
mso setup checks all of these for you in step 5, but it's quicker to have them ready first.
| Requirement | Why | Check |
|---|---|---|
| Python 3.9+ | Maestro is a Python package | python --version |
| Claude Code CLI | Every crew runs as a Claude Code session | claude --version |
| Claude access | Crews call Claude through either your Claude Code subscription login or an ANTHROPIC_API_KEY | claude starts and is logged in |
| git | Every voyage runs on its own branch | git --version |
GitHub CLI (gh), logged in | Opening and updating pull requests | gh auth status |
If you haven't used Claude Code before, install it first. If gh isn't
logged in yet, run gh auth login.
2. Install the package
pip install maestro-fleet
mso version
mso version should print the version you just installed, e.g. Maestro v5.13.1.
- The PyPI package is called
maestro-fleet. The command it installs ismso, and the Python import name ismaestro. - If you ever installed the old
maestropackage, uninstall it first withpip uninstall maestro. pip doesn't know the two packages are related, so installingmaestro-fleetover the old one leaves both in place, and they can shadow each other. mso: command not foundright after installing? pip's scripts directory isn't on yourPATH. On macOS and Linux that is usually~/.local/bin. On Windows it is%APPDATA%\Python\PythonXX\Scripts.
Every install includes the full documentation, readable offline. Run mso docs to list the topics.
For upgrades, uninstalling, and fixing overlapping installs, see
mso docs install-upgrade-uninstall.
3. Activate a licence (paid tiers only)
On the free community tier, skip this step. Community needs no licence and isn't a trial. The setup wizard never asks you for a key.
If you have a Pro, Team, or Enterprise key:
mso licence activate <YOUR-KEY>
mso licence status
Activation needs an internet connection once. After that, Maestro keeps working offline for up to
14 days between checks. For a CI runner or other short-lived machine, set
MAESTRO_LICENCE_KEY=<YOUR-KEY> in the environment instead: Maestro activates on first use.
What each tier unlocks, in brief:
| Community | Pro | Team / Enterprise | |
|---|---|---|---|
| Concurrent crews | 2 | Uncapped | Uncapped |
| Registered projects | 1 | Unlimited | Unlimited |
| Roles | PLN, BLD, TST (and INV) | All | All |
| Maestro Hub (step 7) | No | No | Yes |
Run mso licence status at any time to see your tier. Full reference: mso docs licence.
4. Create a workspace — mso init
A workspace is a .mso/ directory inside your project. It holds that project's orders,
voyages, plans, and config. Run mso init from the root of your project's git repository, with a
short project acronym. The acronym appears in every order ID, e.g. FTR-ACME-2026-0001.
cd path/to/your-project
mso init --project ACME
This:
- creates the
.mso/directory tree with default config under.mso/config/ - writes a starter
CLAUDE.mdfor the project, unless one already exists - adds Maestro's runtime paths to
.gitignore - registers the workspace in
~/.maestro/projects.json, the listmso statusand the Hub read from
Running mso init again on a workspace that already exists changes nothing except the
registration. Add --directory PATH to scaffold a directory other than the current one.
Community tier can register one project acronym. Registering a second acronym needs a paid licence. Re-registering the same acronym, e.g. after moving the repo, always works.
5. Run the setup wizard — mso setup
From inside the workspace, run:
mso setup
The wizard walks through the steps below. Yes/no prompts show the default in capitals ([Y/n]),
and pressing Enter picks it. At a name or template prompt, leaving the answer blank skips it.
| Step | What it does |
|---|---|
| Persona | Shows the active persona (the vocabulary Maestro uses: nautical by default, or another built-in) and offers to change it for this workspace. Purely cosmetic. |
| Prerequisite checks | Checks everything in step 1, plus whether the workspace exists and whether its repository details are still placeholders. Each warning comes with a fix, and some can be repaired automatically. |
| Licence (paid tiers only) | Shows your tier and expiry. |
| Project analysis | Detects your language, framework, test layout, and CI. Nothing is written. |
| SDLC providers | Suggests source-control and CI providers based on your git remote and CI files, asks before saving each one, then offers to test the connection. |
| Workspace configuration | Shows the project acronym. If you answer n to "keep as-is", you can change the acronym and set the default GitHub organisation. |
| Division pack | Lists the packs your tier can use. Press Enter to keep the standard software-delivery workspace. |
| Enrolment profile (paid tiers only) | Looks for an enrolment profile your administrator may have prepared. Most installs have none: the wizard says so and moves on, and there's nothing to do. |
| Requirement templates | Optionally drafts a first order from a built-in template. It's saved for you to review; nothing is queued. |
| Next steps | Prints suggested commands for your project. |
Useful flags
mso setup --check # run the checks only, no prompts; exit code 0 = OK, 1 = FAIL, 2 = WARN
mso setup --repair # run the checks and attempt the automatic fixes
mso setup --show prereqs # read-only view of one section:
# prereqs | project | workspace | templates | persona
mso setup --check --json gives the same results as JSON, for CI.
To run the wizard with no prompts at all (for example when imaging machines), pass
--non-interactive with an answers file of KEY=VALUE lines:
# setup-answers.txt
workspace.project=ACME
workspace.defaultGitHubOrg=acme-corp
providers.scm=github
providers.ci=github_actions
mso setup --non-interactive --answers setup-answers.txt
The provider IDs above are for GitHub with GitHub Actions. If you use something else, run mso setup
interactively once and copy the IDs it detects.
6. Set your repository details
mso dispatch refuses to start while the repository details are still placeholders. It stops
with "Dispatch aborted — workspace still has placeholder repo config" and lists the fields to fix.
There are three of them:
| File | Field | Set it to |
|---|---|---|
.mso/config/workspace.json | defaultGitHubOrg | Your GitHub organisation or user, e.g. "acme-corp". The wizard's Workspace configuration step can set this for you. |
.mso/config/projects.json | projects.<ACRONYM>.repo | "<org>/<repo>", e.g. "acme-corp/acme-app" (replaces your-org/...) |
.mso/config/projects.json | projects.<ACRONYM>.org | The same organisation, e.g. "acme-corp" (replaces your-org) |
While you're in projects.json, check that defaultBranch is right (it defaults to main). Then
confirm everything passes:
mso setup --check
Once the checks pass, the CLI setup is done. mso status shows your fleet, and mso dispatch
starts crews once you've queued work. See the CLI reference for day-to-day
commands.
7. Set up the Hub — mso hub setup
The Maestro Hub is a browser dashboard for every registered workspace: voyages, orders, crews,
the review queue, token usage, and a live lifecycle stream. It needs a Team or Enterprise
licence (step 3) and at least one workspace registered with mso init (step 4).
There are two ways to run it:
| Mode | Use it when | Needs |
|---|---|---|
| Local (default, recommended) | You're a single operator on your own machine | Nothing beyond the pip package. No Node, no Docker. |
| Docker | You're running the Hub on a shared, multi-operator server | Docker with Compose, and the Maestro docker/ deployment files |
Local mode
mso hub setup
mso hub start --open
mso hub setup writes nothing. It:
- lists each registered project as
[ok]or[MISSING](a[MISSING]project's path doesn't exist on this machine, so the Hub can't show it until it does) - confirms the dashboard UI shipped with your install (
[ok] Hub UI bundle present) - prints the start command
mso hub start runs the Hub in the background and serves both the dashboard and its API on
http://127.0.0.1:3847. --open opens it in your browser. The Hub's Python dependencies are
installed automatically the first time it starts. To install them up front instead, run
pip install 'maestro-fleet[hub]'.
mso hub status # is it running? shows the PID and URL
mso hub stop # stop it
mso hub start --port 4000 # use a different port
The Hub listens on 127.0.0.1 only, so other devices can't reach it. Never expose it directly to
the internet. For access from another device, see the mobile-access section of mso docs hub.
Docker mode
Docker runs the Hub's frontend and backend as separate containers. mso hub setup --mode docker
reads your project registry and generates the two machine-specific files the containers need:
| Generated file | What it is |
|---|---|
maestro-home/projects.json | A copy of your project registry with every host path translated to a container path (/repos/<folder-name>) |
docker-compose.local.yml | A Compose overlay that mounts each of your project folders into the container |
mso hub setup --mode docker --dry-run # preview both files without writing anything
mso hub setup --mode docker # write them
Then start the stack from the directory that contains the Maestro docker/ folder:
docker compose -f docker/docker-compose.yml -f docker/docker-compose.local.yml up -d --build
Always pass both -f files. The base docker-compose.yml has no machine paths in it, and your
generated overlay adds your project mounts.
Good to know:
- Where the files go. If a
docker/docker-compose.ymlexists in the current directory or any parent, the files are written to thatdocker/folder. Otherwise they go to~/.maestro/hub-docker/. Use--output-dir DIRto choose a location. - Re-running. Setup won't overwrite files it generated before. After you register a new
project, regenerate with
mso hub setup --mode docker --force. - Don't commit them. Both files contain real paths from your machine.
- Windows paths are converted to forward slashes (
C:/...), which Docker Desktop accepts. If two project folders have the same name, the second gets a-2suffix and setup prints a warning. - Some controls are unavailable in a container. A containerised Hub can't start a dispatcher or
run the housekeeping sweep, because both need
git,gh, and Claude Code on the host. The Hub greys those buttons out and shows the reason. Runmso dispatchfrom a host terminal instead.
Before making a Docker Hub reachable from other machines, set a bearer token (MAESTRO_HUB_TOKEN)
and a host allowlist (MAESTRO_HUB_ALLOWED_HOSTS). Details are in mso docs hub.
Beyond the basics
The steps above give you a complete, working install. Advanced governance configuration (access control, governed mode, custom role and policy setup) is available as part of Enterprise onboarding. Contact us to arrange it.