Quickstart — from zero to a running RAG project in five minutes

This walks through installing Unibench, spinning up the first blessed sample (Postgres + Qdrant + MinIO + a local Ollama model + a Python indexer), and verifying the stack is healthy. Total wall-clock on a fast Mac is around five minutes — most of it is the Ollama model download.

Prerequisites

  • macOS 14 (Sonoma) or later.
  • Apple Silicon (M1/M2/M3/M4) or x86_64 — both supported.
  • ~6 GB free disk for the Ollama model + the blessed binary cache.
  • mise installed (optional but recommended; install with curl https://mise.run | sh or brew install mise). Without mise the orchestrator falls back to whatever runtimes are already on PATH.

1. Install

Download the latest Unibench .dmg from the releases page, drag the app into /Applications, launch it once so macOS registers the bundle, then quit.

The CLI installs alongside the app at /Applications/Unibench.app/Contents/MacOS/unibench. Add it to your PATH:

ln -s /Applications/Unibench.app/Contents/MacOS/unibench /usr/local/bin/unibench

Sanity-check:

unibench ping
# pong

2. Create a project

You have two starting points: drop a ready-made blessed sample into a folder, or scaffold an empty manifest you'll fill in yourself.

Option A — materialize a blessed sample (recommended for the first run)

unibench samples new python-rag-baseline --target ~/Code/my-rag
# wrote /Users/you/Code/my-rag/unibench.toml (+ Python indexer files)

This writes the manifest plus a minimal Python indexer to ~/Code/my-rag/. --target is optional — when omitted, the sample lands at ~/Documents/unibench/<sample-name>/. In the GUI the same flow is Try a sample… → pick the sample → click the Change… button next to "X files will be written to" to redirect the target before you click Create project. Without the override, sandboxed GUI builds land the sample inside the app's container — readable, but buried under ~/Library/Containers/dev.unibench.Unibench/….

Available samples: unibench samples list.

Option B — start empty with unibench init

For a hand-rolled stack (your services, your shapes), write a starter manifest in any folder you control:

mkdir -p ~/Code/my-stack && cd ~/Code/my-stack
unibench init
# wrote /Users/you/Code/my-stack/unibench.toml

The produced unibench.toml carries [project] + [project.schema] and a commented-out block with process, postgres, and redis examples — uncomment and edit to declare your services. Useful flags:

  • --name <name> — override the auto-derived project name (defaults to the directory's basename).
  • --force — overwrite an existing unibench.toml. Off by default so a stray unibench init . in a real project can't clobber it.

Open the project

Whichever path you took, the folder now has a unibench.toml. Open it in the GUI (sidebar → Open Folder…) or via the CLI:

unibench open ~/Code/my-rag    # or my-stack, etc.

3. Start the stack

unibench start ~/Code/my-rag

First run: mise installs Python 3.12 (~30s on a warm cache, longer cold), Postgres + Qdrant + MinIO download (~150 MB combined, one-time), and Ollama pulls the default model (llama3.2, ~2 GB). Subsequent starts are seconds — everything is cached. (If you took Option B and declared only some of those services, only those install.)

Watch the dependency graph in the GUI, or stream status from the CLI:

unibench status ~/Code/my-rag

Every service should land at Healthy.

4. Verify

If you started from python-rag-baseline, it ships a stub ask-server. Once healthy, hit it:

curl http://127.0.0.1:$(unibench env api ~/Code/my-rag \
    | awk '/^PORT/ { print $2 }')/
# python-rag-baseline ask server (stub)

Open Postgres / Qdrant / MinIO inspection drawers from the GUI to confirm each is reachable.

5. Stop

unibench stop ~/Code/my-rag

Or quit the GUI — the daemon's last-client grace will tear down services within a few seconds.

What's next

  • Customize the model. Edit services.ollama.model to mistral:7b or qwen2.5:7b and unibench start again.
  • Swap in your PDFs. Upload to the MinIO corpus bucket and rerun unibench start --seed.
  • Add a frontend. Apply the frontend-vite recipe: unibench recipes apply frontend-vite ~/Code/my-rag
  • Try a different sample. unibench samples list shows the full catalog (agent-loop, embedding-experiments, python-rag-customized).

When things go wrong

  • unibench audit --project ~/Code/my-rag -n 20 shows the last 20 lifecycle events for that project.
  • unibench known-issues lookup "<paste the error>" matches against the embedded catalog of known failures + workarounds.
  • The Diagnose tab on any failing service runs the AI agent against the project state (BYOK; unibench secret set anthropic to wire a key).
  • unibench support-bundle ~/Code/my-rag produces a zip with the redacted manifest, logs, audit log, and graph state for help conversations.