Start here · about 15 minutes

Getting started

By the end of this guide you'll have a project, two registered models with safely stored keys, a routing rule, and a completed first run.

1. Install

Maestro ships as a native installer per platform: MSI/NSIS on Windows, a DMG on macOS, AppImage or .deb on Linux. Run it, launch Maestro, and you'll land in an empty workspace with the canvas in the center, the component tree on the left, the inspector on the right, and the console at the bottom. Dark theme is the default; switch anytime in Settings.

Availability note. Maestro is in staged development — signed installers arrive with the Phase-1 GA stage. Until then, preview builds are produced from source. Everything below describes the product as specified in the public blueprint.

2. Create a project

  1. File → New Project, pick a folder, name it (say, hello-maestro).
  2. Look at the folder Maestro created. Everything is a readable file — maestro.json, models.json, routing/, workflows/. Commit it to git if you like; secrets never live in these files.
hello-maestro/
├── maestro.json        # project settings
├── models.json         # model registry (references only — no keys)
├── routing/default.json
└── workflows/

3. Register your first two models

You bring your own models. Register one hosted model and one local one so you can feel the difference:

  1. Open Models and choose Add model.
  2. Pick a provider — say Anthropic — enter the model name (e.g. claude-sonnet-5), and declare its capabilities (text generation, code generation, vision understanding).
  3. When asked for the API key, paste it once. It goes straight into your OS keychain (macOS Keychain, Windows Credential Manager, or Secret Service on Linux). From now on you'll only ever see •••• and the last four characters.
  4. Click Test connection. Maestro makes one minimal real call and reports latency, or an error message that tells you exactly what to fix.
  5. Now add a local model: if you run Ollama, choose the Ollama provider — no key needed — and register e.g. llama3.3. Local models work fully offline.
Tip. There's no model limit. Register everything you might ever route to — disabled models cost nothing and the registry stays fast well past 500 entries.

4. Point the routing matrix at them

The matrix decides which model handles each kind of task. New projects ship with one empty row per task type:

  1. Open Routing. Find the text-generation row.
  2. Set Primary to your hosted model, and add the local model as Fallback — if the hosted provider ever fails or rate-limits, the run continues locally, and the failover is logged.
  3. Open the test console, type "summarize this paragraph", and confirm the decision trace shows your rule matching. No tokens are spent.

5. Run your first workflow

  1. Create a workflow and drag three nodes from the palette: Input → Model Call → Output.
  2. Connect the ports (text → text — the editor won't let you mis-wire types).
  3. On the Model Call node, choose Route by task type: text-generation — this is the habit worth building; workflows stay portable while the matrix decides models.
  4. Press Run ▶, type a prompt into the Input, and watch: the node pulses, tokens stream into the console, and the routing decision appears in the log ("matched rule 1 → claude-sonnet-5 …").
  5. Open Runs and click the run you just made — every event was recorded and can be replayed later.

Where to go next