Skip to content
Quartermaster Quartermaster

Quickstart

To run Quartermaster locally, clone the repo, npm install, npm run build, and npm start with your scan roots — about two minutes, fully offline. It’s one codebase that runs in three shapes — local, Docker, or a cloud hub — so pick the one that fits, or mix them (a cloud hub fed by collectors on every machine is the full setup). The local shapes run fully offline: the embedding model is baked in at build time, so there are no API keys and no runtime network calls.

Choose your path

Section titled “Choose your path”

Local & offline

The whole registry on your machine — whole-machine crawl, dashboard, and MCP server, no network needed. This page walks you through it below.

Docker

A persistent container with a named volume for the index — loopback-published, token-authenticated, restarts itself. Docker guide →

Cloud hub on Cloudflare

The registry as a Worker (D1 + Vectorize + Workers AI), fed by a thin collector on each device. Secrets are redacted on-device before anything is uploaded. Cloud hub guide →

Guided installers (no terminal)

Feeding a hub from a machine without Node or git? Downloadable collector installers: Windows (five clicks, hourly background scans), macOS (one .run, launchd), and Linux (one .run, systemd/cron).

Not sure? Start local — it’s self-contained and two minutes of setup. You can add a cloud hub and collectors later; there’s also a hub-and-collector mode without Cloudflare where a self-hosted server indexes pushes from other machines.

Local quickstart (whole-machine scan)

Section titled “Local quickstart (whole-machine scan)”

Clone and build (same on every OS):

Terminal window
git clone https://github.com/talberthoule/quartermaster
cd quartermaster
npm install
npm run build

Then download the embedding model (one time) and start the server with the roots you want scanned. The env-var syntax differs per shell, so pick your OS:

Terminal window
$env:TRANSFORMERS_CACHE = ".\.cache"
node dist/prefetch.js          # one-time embedding-model download


$env:DB_PATH = ".\qm.db"
$env:ALLOW_REMOTE_MODELS = "0"
$env:SCAN_ROOTS = "C:\,E:\"
npm start

SCAN_ROOTS="auto" discovers every local volume at scan time instead — Windows fixed drives, Linux local filesystems plus WSL drive mounts, macOS dev-backed mounts. Network shares are excluded so a dead mapped drive can’t hang the crawl.

Scanning is cross-platform — paths are normalized internally, ~ is expanded, and per-OS system trees (Windows Program Files, macOS Library, …) are skipped.

Watch it fill up

Section titled “Watch it fill up”

The server listens immediately and crawls in the background — the MCP is usable right away and the index grows as the crawl proceeds:

Terminal window
curl http://localhost:8765/health      # {"status":"ok","indexed":N,"scanning":true}

Then open http://localhost:8765/ in your browser for the dashboard.

Next steps

Section titled “Next steps”
  • Connect your agent — register the MCP endpoint in Claude Code, Codex, Gemini CLI, Cursor, Cline, or any other MCP client, and install the router skill (it ships in the open Agent Skills format, so one folder works across compatible harnesses — including Pi, which loads Agent Skills natively).
  • Index artifacts from other machines with the thin collector — or run the registry itself in the cloud on a Cloudflare Worker.
  • Tune ports, auth, and scan behavior in Configuration.