laradji/deadzone

> The scraper is still the messy half — #64 is honest about it.
---
The pitch, in one paragraph
Your AI client says "how do I register a tool?". The doc says AddTool. A grep-based index shrugs; a vector index doesn't. Deadzone is the vector index — nomic-embed-text-v1.5 over Turso's native cosine distance, wrapped in a Go binary that speaks MCP over stdio and keeps every byte on your laptop. It is, roughly, Context7 with the internet turned off.
---
Rules of the deadzone
1. **One binary.** deadzone. Subcommands for everything. No pip install, no npm i, no docker compose up.
2. **The index never leaves.** Local Turso file. No account. No API key. No egress on the hot path.
3. **Natural language first.** Embeddings over cosine. FTS5 is not invited.
4. **The binary is the version.** The DB is pinned to the binary. Upgrade the binary, the DB follows; don't, and it won't.
5. **Fail loudly or not at all.** DEADZONE_DB_OFFLINE=1 refuses to guess. Verification failures in the scraper drop the doc, not the run.
---
Install (pick one; they all converge on the same binary)
Both flavors land a deadzone executable in your current directory, so the ./deadzone server snippet below works as-is.
The image bakes the binary, libonnxruntime, deadzone.db, and the nomic-embed-text-v1.5 ONNX weights (~230 MB total), and runs as a non-root user out of distroless (no shell, no package manager). DEADZONE_DB_OFFLINE=1 is set in the image so first launch is instant — no download, no volume mount, no --network access required. To refresh the index, pull a newer tag.
Windows is blocked upstream — no libtokenizers.a. Use WSL.
**Verify checksums** (optional but cheap):
**AppImage needs FUSE v2.** Most desktops ship it; minimal servers don't. If you get dlopen(): libfuse.so.2, either apt-get install libfuse2 (or dnf install fuse-libs) or pass --appimage-extract-and-run to bypass FUSE entirely.
---
Run
That's the quick-start. On first launch it fetches deadzone.db matched to this binary's version, SHA256-verifies, caches it under the platform data dir, and serves. Second launch onwards: zero network. Upgrade the binary and the DB re-fetches on next launch; don't, and the cache is served forever.
MCP client wire-up — native binary (Brew tap, tarball, or AppImage):
MCP client wire-up — container (multi-arch on ghcr.io). The image ships with deadzone.db baked, so no volume mount is needed and every container start is offline-instant:
Then, from the client:
---
The two tools
| Arg | Shape | Notes |
|-------------|-------------------------|-----------------------------------------------------------------------|
| query | string | Matched semantically. Don't write keywords; write what you want. |
| lib_id | /org/project | Optional filter. Grab one from search_libraries. |
| version | "1.14" or similar | Optional pin; **requires** lib_id. version alone is rejected. |
| tokens | int | Response budget. Default 5000, min 1000, ≈ 4 chars/token. |
| limit | int | On search_libraries — max results. Default 10, max 50. |
| name | string | Free text on search_libraries. Empty returns the most-indexed libs. |
---
Under the hood
| Layer | Choice |
|------------|-------------------------------------------------------------------------------|
| Language | Go 1.26.2, pinned via mise |
| Storage | Turso local file — native F32_BLOB(N) + vector_distance_cos |
| Driver | tursogo — **CGO-free** via purego |
| Embedder | hugot → nomic-ai/nomic-embed-text-v1.5, 768-dim, 8192-token ctx (int8 quantized) |
| Runtime | ONNX Runtime — binary CGO-linked at build time; libonnxruntime auto-fetched + SHA256-verified on first launch |
| Protocol | modelcontextprotocol/go-sdk over stdio |
The binary itself is CGO-linked (hugot ORT backend + static libtokenizers.a). At **runtime** the only native surface is libonnxruntime, loaded via dlopen after a SHA256-verified auto-download. Everything else — Go stdlib, tursogo, the model weights — is either statically linked or fetched on first launch against a pinned hash. No system installs. No sudo. If a download drifts from its pinned hash, the run aborts; there is no fallback to an unverified fetch.