maestro-install 0.1.11

One-shot interactive bootstrap for a CARE development workspace.

maestro-install

One-line bootstrap for a CARE development workspace.

Clones every repo the CARE TUI depends on (care, gigaevo-platform, gigaevo-memory, gigaevo-client, carl-experiments, carl-mage) into a directory of your choice and checks out the branch each component is currently developed on.

TL;DR — run from anywhere with uvx

If you have uv installed, you don't need to clone this repo at all. Run:

uvx maestro-install

That fetches the latest maestro-install from PyPI into an isolated, cached environment and launches the interactive wizard. The wizard asks where to put the workspace, how each backing service should be provisioned (local docker stack vs. already-running remote), collects your MAGE provider / key / model, clones whatever you picked "local", writes <workspace>/.env, and can bring the docker stacks up for you.

Re-run uvx maestro-install any time — every prompt defaults to whatever the previous run wrote, so it doubles as a config editor. To force a fresh download of the latest release, add --refresh:

uvx --refresh maestro-install

To pin a specific version:

uvx --from 'maestro-install==0.1.1' maestro-install

Requirements

• git in PATH
• uv (handles Python + PyYAML automatically via the script's inline dependencies)

Quick start — interactive wizard

The fastest path to a working CARE setup is the wizard. It asks how each service should be provisioned (local docker stack vs. an already-running remote), collects the required .env values (MAGE provider + key + model, optional Tavily / Langfuse), clones whatever you picked "local", writes <workspace>/.env, and can bring the docker stacks up for you.

make wizard DIR=~/Development/care-workspace
# or:
uv run wizard.py

It probes uvx maestro and falls back to a local CARE clone if PyPI can't satisfy it. Re-run any time — every prompt defaults to whatever the previous run wrote to .env.

At the end the wizard offers to install a system-wide maestro command (a small shim symlinked into ~/.local/bin). Once it's on your PATH you can run maestro from any directory — the shim cd's into the workspace so .env is loaded, and dispatches to either uvx maestro or the local clone depending on what you chose.

State the shim reads lives at ~/.config/care-install/state.

Preset files and unattended (fast) install

Pass a preset file of CARE_* variables so you don't have to type answers — every prompt is pre-filled from it (you can still hit Enter through them). The preset is a .env-style KEY=VALUE file or a YAML mapping (nested keys join with __); see preset.example.yaml / preset.example.env.

# pre-fill the prompts from a preset, walk through interactively
uv run wizard.py --preset preset.example.yaml

Add --fast (aka -y / --yes) for a fully unattended install — no prompts at all, every default accepted, then it clones, writes .env, and brings the stacks up:

uv run wizard.py --preset my-preset.yaml --fast

In fast mode a required value with no default (the MAGE API key) aborts with a clear message, so make sure your preset sets CARE_MAGE__API_KEY. The preset path can also come from CARE_INSTALL_PRESET, and it may set CARE_DEFAULTS__UI_LANGUAGE to pick the language — that's CARE's own variable, so it drives both the wizard and the CARE TUI.

Export a preset from the current setup — the inverse direction. Pick Export preset from the menu, or run export, to dump your live .env (plus the current language) into a reusable preset file. The extension picks the format (.yaml/.yml → YAML, anything else → .env):

uv run wizard.py export -o my-preset.yaml
# then on another machine / for someone else:
uv run wizard.py --preset my-preset.yaml --fast

The exported file is written chmod 600 and contains your API keys, so keep it private.

Removing CARE (uninstall)

Pick Delete setup from the wizard menu, or run it directly, to wipe every local trace of CARE — it stops and removes the docker stacks (containers, volumes and the images compose built), deletes the workspace / ~/.maestro, removes the maestro shim, and clears the config:

uv run wizard.py uninstall          # asks to confirm first (default: no)
uv run wizard.py uninstall --yes    # unattended (no confirmation)

Manual usage

make prepare DIR=~/Development/care-workspace

Or call the script directly:

uv run prepare.py ~/Development/care-workspace

Re-running is idempotent: existing clones are fetched, switched to the configured branch, and fast-forwarded.

Every run finishes with a verification pass that checks each repo exists, is a git repo, sits on the configured branch, and points at the expected origin. The script exits non-zero if anything fails.

Run the check on its own at any time:

make verify DIR=~/Development/care-workspace
# or: uv run prepare.py ~/Development/care-workspace --verify-only

Override the config path with --config /path/to/repos.yaml.

Running services

maestro talks to GigaEvo Memory (localhost:8002) and GigaEvo Platform (localhost:8000). Bring both stacks up locally with:

make up DIR=~/Development/care-workspace

This runs docker compose -f <file> up -d for every repo in repos.yaml that declares a compose entry. Stop, inspect, tail logs, or restart the same set:

make down DIR=~/Development/care-workspace
make ps   DIR=~/Development/care-workspace
make logs DIR=~/Development/care-workspace
make restart DIR=~/Development/care-workspace

Target a single repo with --only, or run in the foreground:

uv run services.py ~/Development/care-workspace up --only gigaevo-memory
uv run services.py ~/Development/care-workspace up --no-detach

Global c-* commands

For quick access from any directory, install the wrapper scripts in bin/ into ~/.local/bin (or another PATH dir):

make install-cli                 # symlinks bin/c-* into ~/.local/bin
make install-cli BIN=~/bin       # or a custom location

Make sure that directory is on PATH (e.g. export PATH="$HOME/.local/bin:$PATH" in ~/.zshrc). Set the workspace once:

export CARE_WORKSPACE=~/Development/care-workspace

Then from anywhere:

Command	Effect
c-up	bring up all docker stacks
c-down	stop all docker stacks
c-ps	status of all stacks
c-logs	tail logs across all stacks
c-restart	restart all stacks
c-mem-up	GigaEvo Memory only — up
c-mem-down	…down
c-mem-ps	…status
c-mem-logs	…logs
c-mem-restart	…restart
c-plat-up	GigaEvo Platform only — up
c-plat-down	…down
c-plat-ps	…status
c-plat-logs	…logs
c-plat-restart	…restart
c-mage	print MAGE repo path + git status (MAGE is in-process, no docker)
c-ws	print the resolved workspace path

All wrappers forward extra arguments to the underlying services.py / docker compose call:

c-mem-logs -f                      # follow logs
c-plat-up --no-detach              # foreground
c-dev mem up --only gigaevo-memory # explicit dispatcher form

Uninstall with make uninstall-cli (respects the same BIN= override).

Configuration

Origins and branches live in repos.yaml. Each entry:

- name: <local directory name>
  origin: <git remote url>
  branch: <branch to check out>
  compose:                      # optional
    - <path/to/docker-compose.yml relative to the repo root>

Edit the file to add a repo, pin a different branch, point at a fork, or change which compose files make up brings online.