Getting started

The fastest path to a running Bigwave: clone, run ./install.sh, chat in five minutes. The whole 9-step loop runs end-to-end on a single laptop with a consumer GPU.

Prerequisites

Bare-metal default (per ADR 0019):

• Linux or macOS (Windows via WSL2)
• Python 3.12+
• uv (curl -LsSf https://astral.sh/uv/install.sh | sh)
• Ollama (brew install ollama on macOS; curl -fsSL https://ollama.com/install.sh | sh on Linux)
• Optional: an NVIDIA GPU + drivers (otherwise you'll run on CPU, which is slow but functional for the demo)
• Optional: Node.js + npm if you want the embedded Web UI
• ~10 GB of disk for the default model + dataset workspace

If you'd rather use Docker Compose, swap in --install-mode=docker and only Docker + Docker Compose are needed (the installer pulls everything else as container images).

Install

git clone https://github.com/bigwaveml/bigwave.git
cd bigwave
./install.sh                       # bare-metal default (uv + ollama + sqlite)
# or:
# ./install.sh --install-mode=docker   # Compose stack alternative

The installer is interactive by default. It detects your hardware, asks a few questions (port, model, optional Telegram bot), writes .env, runs migrations, builds the Web UI bundle, and prints "next steps" — make dev for foreground or --systemd for a user-mode systemd unit.

For CI / scripted installs:

./install.sh --non-interactive \
    --non-interactive \
    --model=llama3.2:3b \
    --port=8080 \
    --yes-accept-model-licenses

When the installer finishes, save the printed bearer token:

export BIGWAVE_ADMIN_TOKEN=<token-from-installer>

Verify

The Web UI is at http://localhost:8080. The API is at http://localhost:8000/v1.

# Liveness
curl http://localhost:8000/healthz
# {"status": "ok"}

# Models
curl -H "Authorization: Bearer $BIGWAVE_ADMIN_TOKEN" \
     http://localhost:8000/v1/models

# A chat
curl -H "Authorization: Bearer $BIGWAVE_ADMIN_TOKEN" \
     -H "Content-Type: application/json" \
     http://localhost:8000/v1/chat/completions \
     -d '{
       "model": "llama3.2:3b",
       "messages": [{"role": "user", "content": "Hello!"}],
       "stream": false
     }'

Or via the OpenAI Python SDK:

import os
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key=os.environ["BIGWAVE_ADMIN_TOKEN"],
)

resp = client.chat.completions.create(
    model="llama3.2:3b",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)

That's the OpenAI-compatible surface. Every existing OpenAI client works against Bigwave by changing one URL.

Walk the 9-step loop

Each step is a tab in the Web UI. Walk them in order to prove the loop on your machine before reading any further docs.

1. Boot — bare-metal: run make dev (foreground) or systemctl --user start bigwave-api if you used --systemd. Docker mode: the stack is already up after ./install.sh.
2. Chat — open http://localhost:8080 (Docker mode) or http://localhost:8000 (bare-metal default) and have a conversation.
3. RAG — drop a folder of notes into the Knowledge tab. Chat with bigwave_kb_id=notes to ground the response.
4. Train SFT — upload a 50-row JSONL on the Datasets tab, submit a job from the Training tab.
5. Activate — click Activate on the Adapters tab. The serving engine drains in-flight requests and swaps without a restart.
6. Eval — submit an eval run from the Evals tab against a small golden set. Watch the streamed lifecycle and the Wilson 95% CI per pass-rate bucket.
7. Thumbs feedback — click 👍 / 👎 under each assistant message. The Feedback dashboard's rollup updates live.
8. Build a preference dataset — from the Feedback dashboard, pick a pair-strategy and click Build dataset → Train DPO →.
9. Activate DPO + re-eval — same flow as steps 5 + 6. The eval gate refuses promotion if the candidate's pass-rate lower-bound regressed below baseline.

Once you've completed steps 1–9 the loop is proven for your workspace. The runbook in docs/runbooks/feedback-loop.md walks the full cycle with copy-paste curl fallbacks and a reward-hacking checklist.

Where to go next

If you want to…	Read
Understand the architecture before customising	Architecture →
Build a real production setup	Deploy guide →
Use Bigwave for a specific buyer outcome	Use cases →
Understand the deeper concepts	The loop →