Installation

./install.sh is the canonical install path. Per ADR 0019, the default mode is bare-metal (uv + Python on the host); Docker Compose is a fully-supported alternative via --install-mode=docker.

When to pick which mode

You want…	Use mode
Local development, hot-reload, IDE integration	baremetal (default)
Regulated environment that forbids Docker	baremetal
One-stop multi-service stack (Postgres + Phoenix + nginx all bundled)	docker
Already standardised on Compose / k8s in your org	docker
Run the agent harness with sandboxing	docker (sandboxing requires Docker per ADR 0018)

What ./install.sh does (bare-metal default)

1. Detects OS / arch. Uses detect_os + detect_arch from deploy/installer/detect.sh. No Docker requirement.
2. Asks for configuration (interactive) or reads flags (non-interactive): profile, model, port, optional axis overrides.
3. Checks uv is installed. If not, prints the one-liner install command and exits — never auto-installs silently.
4. Checks ollama is in PATH. Platform-specific install instructions if missing (brew install ollama on macOS, curl -fsSL https://ollama.com/install.sh | sh on Linux).
5. Writes .env — atomic write of resolved Settings.
6. uv sync — provisions .venv/ with the locked Python dependencies.
7. alembic upgrade head — runs migrations against the configured BIGWAVE_STORAGE_URL (SQLite by default).
8. Builds the Web UI bundle if npm is available (apps/web/dist/). Skipped gracefully if Node isn't present.
9. Pre-pulls the configured model via the host ollama.
10. Optionally writes a systemd unit when --systemd is supplied (user-mode unit at ~/.config/systemd/user/bigwave-api.service).
11. Prints next-step instructions — make dev for foreground, systemctl --user enable --now bigwave-api for systemd.

What ./install.sh --install-mode=docker does

1. Detects hardware + Docker. detect_all from deploy/installer/detect.sh; refuses to proceed without Docker.
2. Renders docker-compose.yml from the resolved axis values.
3. Pre-pulls the model via the in-stack Ollama service.
4. docker compose up -d + waits for /healthz.
5. Prints the access URL and admin token.

Axis flags

Every axis has a default; pass a flag to override it. Each --<axis>=<value> flag maps 1:1 to the matching BIGWAVE_<AXIS> environment variable that the API reads at startup. The shipped/roadmap split below is generated from deploy/installer/profiles.sh; roadmap values fail fast at install time with a ships in Phase N message.

Flag	Env var	Default	Shipped values	Roadmap values
--gateway	BIGWAVE_GATEWAY	firstparty	firstparty, litellm	—
--storage	BIGWAVE_STORAGE_URL	sqlite	sqlite, postgres	—
--vector	BIGWAVE_VECTOR	lancedb	lancedb, pgvector, qdrant, milvus	—
--serving	BIGWAVE_SERVING	ollama	ollama, vllm, llama_cpp, sglang, tgi	—
(hardcoded)	BIGWAVE_TRAINING	unsloth	unsloth, axolotl, llama_factory, raw_peft_trl	—
--observability	BIGWAVE_OBSERVABILITY	stdout	stdout, phoenix, langfuse	—
--runner	BIGWAVE_RUNNER	arq	arq	ray
--auth	BIGWAVE_AUTH	bearer	bearer, proxy_headers	oauth, oidc, saml
--channels	BIGWAVE_CHANNELS	web	web, telegram, slack (comma-separate)	discord
--guardrails	BIGWAVE_GUARDRAILS	off	off, dsl, llama_guard	dsl+classifier
--sandbox	BIGWAVE_SANDBOX	subprocess	subprocess, docker	firecracker, gvisor, e2b, bubblewrap, wasm

./install.sh --non-interactive \
    --storage=postgres \
    --observability=phoenix \
    --auth=proxy_headers \
    --sandbox=docker

Manual install (advanced)

If you want to run Bigwave without ./install.sh — for example inside an existing Compose stack or in Kubernetes — the moving parts are:

# Python deps (uv recommended)
uv sync
source .venv/bin/activate

# Database migrations
alembic upgrade head

# API
uvicorn apps.api.main:app --host 0.0.0.0 --port 8000

# Web UI
cd apps/web && npm install && npm run build
# Serve dist/ behind your favourite reverse proxy

Required env vars at minimum:

BIGWAVE_ADMIN_TOKEN=<a strong secret>
BIGWAVE_STORAGE_URL=sqlite+aiosqlite:///./bigwave.sqlite
BIGWAVE_MODEL=llama3.2:3b
BIGWAVE_OLLAMA_URL=http://localhost:11434

See the configuration reference for the full env-var inventory.

Re-running ./install.sh

The installer is idempotent. Common operations:

Goal	Command
Reconfigure (port, axes, model)	./install.sh and answer the prompts
Add a new model	./install.sh add-model <name>
Upgrade to a newer Bigwave release	./install.sh upgrade
Regenerate the admin token	./install.sh regenerate-token
Wipe and start over	./install.sh reset (asks for confirmation)

Uninstall

docker compose -f docker-compose.yml down -v
rm -rf .env docker-compose.yml ./bigwave.sqlite ./logs ./data

Troubleshooting

Port 8080 already in use. Pass --port=<other> to the installer.

docker compose not found. You need Docker Compose v2 (the plugin), not the legacy docker-compose standalone binary. Most modern Docker installs ship the plugin by default.

Model download stalls. The default model is ~2 GB; large models can be 30+ GB. The installer prints progress every 5 seconds; if it hangs for >2 minutes, check Ollama's logs: docker compose logs ollama.

API returns 401 on every request. Confirm the bearer token in your client matches $BIGWAVE_ADMIN_TOKEN. The installer prints the token at the end; re-run ./install.sh regenerate-token if you lost it.