Run Your First Workflow

1. Open the desktop app

On first launch, use the setup flow to confirm:

• your default workspace path
• Git readiness and any automatic installation prompt if Git is missing
• local model availability if you are using Ollama or another local runtime
• optional CLI shell integration if you want maabarium available in Terminal through the managed ~/.local/bin/maabarium link
• any provider credentials needed for the blueprint you want to run

If you are using Ollama, the setup flow keeps the model step explicit:

• install Ollama if it is not present yet
• start Ollama if the local service is not running yet
• use Pull Recommended Models after Ollama is running to download the suggested local models for bundled workflows

If you plan to use research-oriented workflows, the same setup flow also lets you choose how web search should work:

• DuckDuckGo scrape keeps the default local-first path with no separate Brave API credential requirement
• Brave API uses the Brave-backed search path when that credential is configured

Setup modal walkthrough

The guided setup modal keeps Git readiness, shell CLI setup, workspace selection, and Ollama model pulls in one place before the first run.

Use the setup modal in this order:

1. Choose the experience mode and runtime strategy first. That decides whether you are optimizing for a local Ollama flow, a remote-provider flow, or a mixed setup.
2. Resolve machine-level prerequisites next. The same modal surfaces Git readiness, the optional Install CLI Link action for ~/.local/bin/maabarium, shell PATH guidance, and the default workspace selector.
3. Finish the local runtime section before starting a workflow. If Ollama is already running, Pull Recommended Models downloads the suggested local models without making you drop into Terminal and run individual ollama pull commands.

When those sections look healthy, save setup and move on to blueprint selection.

2. Pick a workflow

Start with one of the bundled workflow blueprints from the workflow library. If you are learning the system, avoid the most ambitious templates first. Choose something that lets you verify the loop end to end.

3. Confirm the workspace

When Maabarium asks where to run the workflow, point it at a real project directory. If the folder is not already a Git repository, Maabarium can initialise one for you so future branching and evaluation steps behave correctly.

If Git itself is missing, the desktop setup flow or CLI run path should tell you that directly. On supported systems, Maabarium will attempt to install Git automatically instead of failing silently.

4. Start the run

Use the desktop Run Flow action or the CLI if you prefer terminals.

cargo run -p maabarium-cli -- run blueprints/example.toml --db data/maabarium.db

CLI runs now perform a Git preflight before the workflow starts. After the run finishes, the CLI also prints an aggregated timing summary so you can see phase totals and average iteration cost without digging through raw logs.

If you are using the desktop app, watch the console section for:

• latest proposal activity
• logs
• research evidence or evaluation output
• status changes between idle, running, and stopping

5. Review what happened

A successful first run should leave you with visible evidence, not just a green check:

• persisted experiments
• proposals or evaluation logs
• an updated Git workspace or branch history
• a CLI timing summary if you launched the run from the terminal
• enough context to understand why the result was accepted or rejected

If the first run fails

Go directly to Troubleshooting. The common issues are almost always environment, model availability, workspace state, or credentials.