Step-by-step guide to run Minnow from a git clone for development. End users should download a packaged build from Releases and follow Install and first launch. Index: ../README.md. Architecture orientation: architecture.md. Exhaustive reference: ../context.md.

Native modules (better-sqlite3, @lydell/node-pty) ship prebuilt binaries for common platforms. A C/C++ toolchain is only required if npm falls back to building from source.

git clone https://github.com/HenriGrimm/Minnow.git
cd Minnow
npm install

postinstall automatically:

• vendors the Impeccable UI-design skill into src/skills/impeccable/ (scripts/sync-impeccable-skill.mjs) — the shipped copy Minnow installs into ~/.minnow/skills/impeccable/ at runtime, and
• ensures the Electron binary is present (scripts/ensure-electron.mjs).

Both are idempotent — safe to re-run.

PDF/Word/Excel attachment support comes from optionalDependencies, which install best-effort. If an attachment type fails, install it explicitly:

npm install pdf-parse mammoth officeparser
# xlsx is fetched from the SheetJS CDN per package.json

You need at least one OpenAI-compatible endpoint. Easiest is LM Studio:

1. Install and open LM Studio.
2. Download and load a chat model.
3. Open the Developer / Server tab and Start Server (default http://localhost:1234).
4. Confirm the model is listed in LM Studio's server UI.

Alternatives — all configured in the Models app under Providers:

• Ollama — point Minnow at http://localhost:11434.
• llama.cpp llama-server — or let the Models app download and serve a model for you.
• Cloud APIs — any OpenAI-compatible base URL + API key (stored encrypted).

curl -fsSL https://lmstudio.ai/install.sh | bash
export PATH="$HOME/.lmstudio/bin:$PATH"
lms daemon up && lms server start
lms get <model-name> -y
lms load <model-name> -y

npm start

This starts Vite + the Node tool server on port 9473 (or the next free port — watch the terminal) and launches the Electron desktop shell. It also prints Minnow data: <path> showing your ~/.minnow home.

npm start, npm run desktop, and npm run electron:dev save server and Electron output under ~/.minnow/logs/runtime/server/ and ~/.minnow/logs/runtime/electron/ (or your MINNOW_HOME). Each run has stdout.log, stderr.log, and events.log files prefixed with its timestamp and supervisor PID. Check the newest stderr and events files after an unexpected exit; events include child PIDs, exit codes, and signals. Previous runs survive restart. Files rotate at 4 MiB with two backups, and old inactive runs are pruned on startup to retain ten runs, plus older live supervisors. Logging starts on the next launch after updating source. These logs are local and may contain application output; review them before sharing.

PORT=5173 is deliberately ignored and coerced back to 9473 — 5173 is reserved for dev servers in your workspace, so agents can start a Vite app without colliding with Minnow.

Use npm start (not npm run dev) whenever you need file/git tools, persistence, terminal, attachments, browser preview, or any of the apps.

Every /api/* route requires the per-boot session token in ~/.minnow/session-token:

curl -H "X-Minnow-Token: $(cat ~/.minnow/session-token)" http://localhost:9473/api/tools/ping
# {"ok":true}

curl.exe -H "X-Minnow-Token: $(Get-Content $env:USERPROFILE\.minnow\session-token)" http://localhost:9473/api/tools/ping

A bare request without the header returns 401 Unauthorized — that is the gate working, not a broken server.

1. Provider — Models → Providers: confirm the base URL and that the provider is reachable.
2. Model — pick one from the menubar model chip (use refresh if empty). Vision tasks need a VLM; tool-calling models work best for agent turns.
3. Mode — composer: General / Build / Plan / Debug. (Orchestrate opens from the sidebar hub, not the composer picker.)
4. Tools — Settings → Tools & integrations → Tools: enable capabilities; set per-tool permission (full / ask / off). Server tools need npm start and a healthy tools ping.
5. Workspace — open Code and pick a project folder; file/git tools resolve under this root.

• WSL / Git Bash (Windows) — Settings → General → Chat & terminal → Default shell. Git Bash appears when Git for Windows is installed; WSL distros appear when WSL is installed. Requires npm start.
• Voice — Models → Voice: local Whisper / Qwen3-TTS or provider APIs.
• Memory & Brain — the Brain app owns memory settings and embeddings.
• MCP — Settings → Tools & integrations → MCP servers: Context7 built in; add custom servers.
• Skills — Settings → Tools & integrations → Skills / Skills Library: 19 built-in skills ship in-tree, plus third-party SKILL.md packs.
• Webhooks — Settings → Tools & integrations → Webhooks: HMAC-signed outbound deliveries.

Compare, Benchmarking, and Experts are release-gated off in this build — see apps-and-routes.md.

• commands.md — scripts, tests, env vars
• architecture.md — three-process map
• orchestrate-board-testing.md — board test harness
• ../manual/reference/configuration.md — ~/.minnow layout
• tool authoring, agent packs