The wizard CLI.
A single static binary that manages the backend and frontend as a background service — the same subcommands on Linux, macOS and Windows.
Subcommands
wizard initChecks Python 3.12+/Node 20+/uv/pnpm (and optional Ollama) are on PATH; copies backend/.env.example, creates a managed venv, installs backend requirements, builds the frontend's production bundle. --pull-models also pulls a default manager/worker pair.
wizard startLaunches backend + frontend as a detached background supervisor, waits until the backend answers healthy, checks API version compatibility, opens a browser. --backend-port/--frontend-port override 8000/3000; --no-browser skips opening one.
wizard stopIdempotent. Asks the supervisor to stop and waits for cleanup; falls back to a forced kill of recorded pids.
wizard status / wizard doctorSame command. Local checks (what's running, log sizes, API_PROVIDER/DATA_MODE, EXECUTION_BACKEND) plus a render of the backend's own GET /api/config.
wizard attachPrints status, then follows backend.log/frontend.log live, source-prefixed, until Ctrl+C. Read-only.
wizard logsOne-shot: prints the log file paths; --tail N also prints the last N lines of each.
wizard updategit pull --ff-only, reinstalls dependencies the same way init does, re-checks the compat marker. Restarts the daemon afterward if it was running before.
wizard skills add/list/update/discard/remove/tokenFronts the built-in skill installer — fetch, pin to a commit, show contents, ask before writing.
wizard versionPrints this binary's compiled-in compat version.
Setup recipes
wizard init configures a local, hybrid or fully cloud install in one run — every flag is also safe to run again against an already-configured backend/.env.
Local-only — Nothing leaves your machine. No API key.
wizard init
Hybrid — Keep local models, make a cloud key available for either role.
wizard init --data-mode hybrid --anthropic-key sk-ant-...
Cloud-only — No local weights needed — Anthropic, OpenAI, Gemini, or any gateway.
wizard init --provider anthropic --anthropic-key sk-ant-...
Any OpenAI-compatible gateway — Groq, OpenRouter, Together, vLLM.
wizard init --provider custom_gateway --gateway-url https://api.groq.com/openai/v1 --gateway-key gsk_...
Configuration
Copy backend/.env.example to backend/.env. Everything has a working default.
| Key | Default | Purpose |
|---|---|---|
| API_PROVIDER | ollama | Default backend: ollama, lmstudio, anthropic, openai, gemini or custom_gateway |
| DATA_MODE | "" (derives) | local-only, hybrid or cloud-only — what may leave this machine |
| MODEL_NAME | "" | Pin the reasoning model. Empty = use what the provider has |
| WORKER_MODEL_NAME | "" | Pin the code model. Empty = use what the provider has |
| AGENT_TIER | auto | auto, compact, balanced or full — how long an investigation may run |
| AGENT_VERIFY | True | Recompute the headline result a second way |
| EXECUTION_BACKEND | host | host (subprocess, no Docker), docker or inprocess |
| SANDBOX_TIER | standard | core, standard or full — how much toolkit the image installs |
| HOST_SANDBOX | best-effort | off, best-effort or require — OS containment for the host runtime |
| PLOT_FORMAT | html | html for interactive Plotly, png for static |
| CORS_ALLOW_ORIGINS | http://localhost:3000 | Comma-separated allowlist |
| API_KEY | "" | When set, mutating routes require X-API-Key |
Resource limits — LLM_NUM_THREAD, SANDBOX_MEM_LIMIT, SESSION_MAX_ACTIVE— are left unset on purpose. They're derived from the machine at boot; setting one pins it.
Common issues
A question takes many minutes, or never finishes
Check whether MODEL_NAME is a reasoning model (deepseek-r1, qwq) — by far the most common cause. Use a plain instruct model for the manager role; a reasoning model is fine as the worker.
Is LLM_NUM_THREAD set in backend/.env?
Delete it. Local inference is memory-bandwidth bound, so more threads than physical cores is contention, not throughput. Unset, it's measured from the machine.
"Local subprocess" instead of "Docker container"
Docker is unreachable, so code runs in a subprocess of the backend — bounded, interruptible, and it keeps variables between steps, but not isolated from your filesystem.