Install and run Breeze on your own hardware.
Breeze runs entirely on your own hardware. This guide walks through the three processes you need up: the Next.js frontend, the FastAPI backend, and Ollama.
| You need | Version | For |
|---|---|---|
| Bun | latest | Package manager and runtime for the frontend. |
| Python | 3.10+ | Runs the FastAPI backend. |
| MongoDB | local or Atlas | Users, conversations and messages. |
| Ollama | running | Serves the models. Must be reachable by the backend. |
bun install
bun run devThe dev server comes up on localhost:3000.
Copy .env.example to .env.local and fill it in:
OLLAMA_API_URL= # FastAPI backend URL, e.g. http://localhost:8000
OLLAMA_API_KEY= # Shared secret for the backend's X-API-Key
MONGO_URI= # MongoDB connection string
NEXTAUTH_SECRET= # JWT signing secret
NEXTAUTH_URL= # App URL, e.g. http://localhost:3000
PLATFORM_PASSWORD= # Demo account passwordTwo names, one secret
OLLAMA_API_URL points at the FastAPI backend, not at Ollama directly --
the frontend never talks to Ollama. And OLLAMA_API_KEY here must be byte-for-byte
the same value as API_KEY in backend/.env, or every request comes back 401.
cd backend
python main.pyEither way FastAPI listens on port 8000. Create its env file:
API_KEY= # Shared secret; must match the frontend's OLLAMA_API_KEY
TAVILY_API_KEY= # Optional: only needed for web searchRequests are authenticated with the X-API-Key header and rate-limited per
client IP: 10/minute on /completion, 20/minute on /summarize.
Breeze talks to Ollama's OpenAI-compatible endpoint, http://localhost:11434/v1
by default. Pull the models for the modes you plan to use:
./install.sh # reads backend/models.json and pulls exactly that setOr by hand:
ollama pull phi4-mini:3.8b # default chat and summarisation
ollama pull qwen3-vl:8b-instruct # vision and generative UI
ollama pull qwen3:8b # reasoning / thinking mode
ollama pull qwen2.5:7b # web searchOnly phi4-mini:3.8b is required to send a first message. The others are pulled
on demand by the mode that needs them -- see
model selection.
Prefer the -instruct tag
For the vision and generative-UI roles, use a model's -instruct tag rather
than its thinking tag. A thinking model spends the capped completion budget on
reasoning and can return an empty answer -- the bare qwen3-vl:8b resolves to
the thinking variant and renders no widget on most turns.
Override the endpoint with OLLAMA_BASE_URL in backend/.env if Ollama runs
on another machine.
Check the backend answers:
curl http://localhost:8000/health
# {"status":"ok"}Then open localhost:3000/chat, sign up, and send
a message. The reply streams in from your local model.
That is the whole install
Nothing so far has contacted a vendor. If you never turn on web search or set Langfuse keys, nothing ever will.