Skip to content
Quartermaster Quartermaster

Cloud hub on Cloudflare

Quartermaster can run its brain in the cloud: a Cloudflare Worker serves the registry of record, hybrid search, the MCP endpoint, and all pure-analysis tools, while a thin collector on each machine does the only thing a cloud runtime can’t — crawl your local drives. Everything runs in your own Cloudflare account — the free tier covers a personal registry comfortably.

your machines                          Cloudflare
─────────────                          ──────────
collector (per device, scheduled) ──►  Worker front door
 · crawl scan roots                     · /mcp → 21 MCP tools
 · classify / parse / REDACT            · /api/ingest → embed (Workers AI)
 · snapshots + git provenance           · D1 (FTS5 BM25) + Vectorize (kNN)
 · applies hydration on-device  ◄────   · plans, approvals, jobs queue

What runs where

Section titled “What runs where”
  • Worker (worker/ in the repo): search, fetch, census, conversion, compatibility, packs, risk scanning, drift explanation, MCP-surface diffing, hydration planning and approval — 21 MCP tools total. Storage is D1 (same SQLite + FTS5 engine as the local build) plus Vectorize for vectors; embeddings come from Workers AI (bge-m3, 1024-d).
  • Collector (src/cloudCollector.ts): the scanner’s crawl → classify → parse → redact pipeline, run locally. Secrets are stripped before anything leaves the machine. It also executes approved hydration jobs — file writes only ever happen on-device.

Deploy the Worker

Section titled “Deploy the Worker”

Fastest path — the setup script. One command provisions everything (D1 + Vectorize, schema, deploy, AUTH_TOKEN, health check), idempotently:

Terminal window
cd worker && npm install
npx wrangler login   # once
node setup.mjs       # prints the generated AUTH_TOKEN once — save it

Or set it up by hand / deploy-on-push. The recommended long-term path is Workers Builds — Cloudflare pulls from your GitHub fork and deploys on push; no API token ever leaves Cloudflare. One-time setup (details in worker/SETUP.md):

  1. Create the Vectorize index first (quartermaster-index, 1024 dimensions, cosine) — a build deployed before the index exists fails on the missing binding.
  2. Connect the repo in the dashboard (Workers & Pages → Create → Import a repository), root directory worker.
  3. After the first deploy, set the AUTH_TOKEN secret — the Worker answers 500 on /mcp and admin routes until it’s set (fail-closed by design).

Then point your agent at it:

Terminal window
claude mcp add --transport http quartermaster \
  https://quartermaster.<your-subdomain>.workers.dev/mcp \
  --header "Authorization: Bearer $AUTH_TOKEN" --scope user

Feed it: the cloud collector

Section titled “Feed it: the cloud collector”

On each machine that should populate the registry (the guided installers for Windows, macOS, and Linux do all of this for you):

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


# one-time pairing — the admin token is used once and never stored;
# only a revocable device-scoped token lands on disk (0600, ~/.quartermaster/)
QM_ADMIN_TOKEN=<AUTH_TOKEN> node dist/cloudCollector.js connect \
  --url https://quartermaster.<your-subdomain>.workers.dev \
  --roots "$HOME/.claude,$HOME/.codex,$HOME/.gemini,$HOME/.hermes"


node dist/cloudCollector.js scan     # incremental — diffs local state, uploads changes only
node dist/cloudCollector.js jobs     # picks up rescan/hydration jobs queued by the cloud
node dist/cloudCollector.js loop --interval-min 30   # scan + jobs, forever
node dist/cloudCollector.js status   # local config + tracked count + server health

For unattended machines, schedule scan + jobs with Task Scheduler (Windows), launchd (macOS), or a systemd user timer / cron (Linux, WSL).

Security properties

Section titled “Security properties”
  • Pairing is one-shot. The admin token authorizes pairing once and is never persisted; each device gets its own token, revocable server-side.
  • Redaction happens on-device. Env and header values are dropped (key names kept) at parse time — raw secrets never reach the wire.
  • The cloud can plan, only the device can write. apply_hydration produces an approved job; the collector executes it locally and reports back.
  • Fail-closed auth. Without AUTH_TOKEN, the Worker refuses /mcp and admin routes rather than serving openly.

Local hub instead?

Section titled “Local hub instead?”

If you’d rather keep everything on your own network, the same produce/sink seam works against a self-hosted hub — see Collector & hub.