| Deep32 Design | November 2026 | |
| Cummings | Informational | [Page] |
Deep32 lets an agentic language model working in a terminal, such as Claude Code or Codex, answer networking questions from a local corpus of RFCs and vendor documentation, and check every quotation against the stored text. Retrieval, verification and the index run on the user's own machines; the language model is the only hosted part.¶
This report describes the design of release 0.1.0-alpha.2: the corpus and index format, the hybrid retrieval pipeline, the eleven tools the agent calls, the three machines a deployment consists of, the protocols between them, the signed release format, and the evaluation behind the numbers it quotes.¶
This is Deep32 Technical Report 1 (D32-TR-1), the design reference for Deep32 release 0.1.0-alpha.2, published by its author. It is not a product of the IETF or of any other standards body and has no standing there. It uses the RFC format because the system it describes is built around RFCs, and because the format is good at stating behavior precisely.¶
Each Deep32 release that changes the design updates this report under a new version of its DOI. Errors can be reported on the project's issue tracker.¶
This version: DOI 10.5281/zenodo.24326998.¶
Copyright (C) 2026 Jeffrey A. Cummings. This document is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0). Text quoted from RFCs remains subject to the IETF Trust's Legal Provisions Relating to IETF Documents.¶
Language models get networking specifics wrong in ways that are hard to spot without opening the source document. Deep32 gives an agent a local corpus, a retrieval pipeline tuned on that corpus, and tools that check what the agent quotes. The agent still writes the answer; Deep32 puts the evidence where the agent can find it and read it in full, and checks quotations mechanically. The arrangement is the usual retrieval-augmented one [RAG], with two retrievers instead of one and the retrieval exposed to the agent as tools.¶
This report covers how the system is built. The reasons for each choice, with the alternatives I ruled out and the measurements behind them, are in the Deep32 Decision Record [D32-DR]; this report cites its entries as DR-nn. The software, images and this report are archived with the release [DEEP32].¶
Deep32's code is licensed under the Apache License, Version 2.0 [APACHE-2.0], with a NOTICE
file that names its author and goes with every copy. The two parts that use MuPDF, the Forge's PDF converter
and the Workstation Library's renderer e26-render, are licensed under AGPL-3.0-or-later
[AGPL-3.0] (DR-110). This report and the other documentation are under CC BY 4.0.¶
Most errors I see in model answers about networking fall into four groups:¶
Two of these can be checked mechanically: an RFC's status is a lookup, and a quotation either occurs in the stored text or it doesn't. The other two depend on the agent noticing a difference that the corpus makes visible. Deep32 returns RFC text and vendor text as separate sources, tags every passage with its platform and release, and has the agent follow a fixed protocol (Section 7.4) that compares them.¶
In scope: the corpus, the index and its build, retrieval, the verification tools, the deployment of the three parts, the network protocols between them, the release format, and the retrieval evaluation.¶
Out of scope: the language model, which its provider hosts, and the quality of the answers it writes. Retrieval quality is measured (Section 13); answer accuracy has not been measured yet, and this report makes no claim about it.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
In this report they state the behavior of the released implementation. A reimplementation of one of the protocols in Sections 10.3, 11 and 12 interoperates only if it follows the same rules.¶
doc_type: rfc, cisco,
powershell or system.¶
A deployment has three parts on one tailnet (Figure 1). They can share a machine or sit on three; the protocols and the configuration are the same either way.¶
+------------------+ MCP over HTTPS, +--------------------+
| Headend | agent's own token | Workstation |
| agent + skill |----------------------->| gateway, engine, |
| Ask relay |<======================>| index, Ask, |
+------------------+ D32U/1, mutual TLS | Library |
(Workstation dials) +--------------------+
|
embeddings and | HTTPS,
reranking | Forge token
v
+--------------------+
| Forge |
| embedder, |
| reranker, |
| builder (option) |
+--------------------+
The Workstation holds a whole generation and runs the engine locally. It calls the Forge only to embed a query and to rerank candidates, so it still answers keyword searches when the Forge is off (DR-50, DR-58).¶
| Image | Contents | Installs |
|---|---|---|
| Disc 1 | Bootable OpenBSD installer with the Deep32 system | Workstation |
| Disc 2 | Corpus, a prebuilt generation, and the Deep32 Library | Content, imported by the Workstation |
| Disc 3 | GPU pack: a shared core, one embedder add-on per card class, and an ingestion add-on (all three installed on a Forge in 0.1.0-alpha.2, DR-106) | Forge |
The release itself is a small set of signed metadata on GitHub that names the images and where to get them (Section 12).¶
An agent reaches Deep32 in one of two ways.¶
A question typed on the Workstation travels over the Ask link to the relay on the headend:¶
An Ask session needs no MCP entry on the headend and never reaches the gateway over the tailnet.¶
| doc_type | Documents | Passages | Contents | Default |
|---|---|---|---|---|
| rfc | 365 | 12,041 | IETF RFCs | Yes |
| cisco | 489 | 49,923 | Configuration guides, command references, TechNotes, validated designs and other Cisco documentation | Yes |
| powershell | 241 | 5,149 | Windows PowerShell 5.1 help, 7.x differences, networking modules | No |
| system | 85 | 695 | Deep32's own code, configuration and design notes | No |
| Total | 1,180 | 67,808 |
Restricted and non-redistributable collections from my own deployment are not in the public release. Every derived table (lookups, outlines, catalog) in the release was rebuilt from the kept collections, and every row in it cites a kept document (DR-17). The Cisco documentation remains Cisco's copyright; RFCs fall under the IETF Trust's provisions.¶
The opt-in collections have their own FTS5 table, so a default search ranks exactly as it would if they
didn't exist (Section 6.2, DR-14). A request reaches them only by naming them with
doc_type or docs.¶
Each document has a manifest entry with its key, type, title, path, source and page URLs, platform, release, SHA-256, size, license, terms URL, a redistribution flag and its near-duplicates (Figure 2). The platform and release drive release-aware search (Section 6.7); the license and redistribution flag decide what may ship.¶
{
"doc_key": "rfc4271",
"title": "A Border Gateway Protocol 4 (BGP-4)",
"doc_type": "rfc",
"path": "rfc/rfc4271.txt",
"source_url": "https://www.rfc-editor.org/rfc/rfc4271.txt",
"sha256": "98b851146abcd56ecbb398dd1a818bcd
e2dcac6fde3d901c423d988f86eaab76",
"bytes": 222702,
"redistribute": true
}
The digest is shown wrapped to fit; it is one string.¶
Documents come from their publishers' own sites. The fetcher sends an honest User-Agent and keeps a daily byte budget with a 24-hour cool-off after a refusal (DR-09). HTML and PDF are converted to plain text in a sandbox with no network access. Every new document then passes quality checks and a scan for lines that read as instructions, invisible characters and control bytes; a person reviews each flagged line before the document is admitted (DR-11).¶
Some questions are lookups: whether an RFC is current, what an IANA code point means, or the exact syntax of a command. A ranked search can return a close but wrong passage for those, so each build also produces tables that the identifier tools read directly (DR-16):¶
The RFC index covers the whole RFC series, not only the 365 RFCs whose text is in the corpus, so
lookup_rfc can report the status of any RFC an answer cites.¶
| Identifier | Form | Derivation |
|---|---|---|
| Document |
doc_ + 64 hex digits |
SHA-256 of the source file |
| Passage |
chk_ + 64 hex digits |
SHA-256 over the document hash, the passage's position and its text |
| Vector point | UUID | UUID version 5 [RFC9562] in the URL namespace, of a fixed prefix and the passage ID |
Because the identifiers derive from content, a passage whose text and embedding input did not change keeps its ID and reuses its vector in the next generation (DR-42). One update embedded 904 new passages and reused 62,617. The content image reuses all 67,808 vectors of the generation it was cut from.¶
A generation ships as a knowledge-base bundle (contract C3 in the repository), shown in Figure 3.¶
<generation>/
BUNDLE.json compatibility record (Table 3)
MANIFEST.json every other file with size and SHA-256
root/
sqlite/rag.db documents, sections, passages; FTS5 tables
kb/kb.sqlite RFC index, errata, IANA, CLI, glossary,
feature history
sources/ the corpus the generation was built from
config/ serving settings for this generation
BUILD_REPORT.json
dense/
vectors.f32 N x D float32, little-endian, point order
points.bin N records of 96 bytes: point, passage and
document IDs, flags
EXPORT.json collection settings, counts, digests
| Field | Value |
|---|---|
| format, format_version | "deep32-kb-bundle", 1; readers refuse any other |
| generation, fingerprint | The generation name; the corpus fingerprint (16 hex digits) |
| created | A UTC time given to the builder, never read from the clock, so the same inputs give the same bytes |
| engine | The range of engine versions that may serve the bundle |
| embedding | Model ID, revision, dimension (1024), number format (float32-le), distance (cosine), pooling (last-token), and the query and document prompts |
| reranker | Model ID and revision used by the build's checks |
| blocks, counts, opt_in | The corpus blocks, per-collection counts, and the opt-in collections |
| manifest_sha256, signer | Digest of MANIFEST.json, and the key that signed the bundle |
An importer accepts a bundle only when its signature holds, every file matches MANIFEST.json, both formats
are known, the installed engine lies in the engine range, and the embedding model ID, revision and
dimension equal what the paired Forge serves. On that last mismatch, meaning search stays off and the
importer says why. Disc 2's bundle is trusted through the release signature; a bundle a user's own Forge
builds is signed with that Forge's key, which the Workstation enrolled at pairing.¶
Passages are cut by heading scope: text merges within one top-level section and never across it, and a table that has to be split repeats its caption and header row in every piece (DR-36). Each passage is embedded with its document title and heading path (Section 6.3). The build writes the FTS5 tables, the section index, the vectors and the lookup tables, then a build report.¶
On a Forge, a new generation starts from a clone of the previous generation's vector snapshot and adds to it. Two approximate-index builds from identical vectors differ by a question or two at rank 1, which would make a zero-slack gate a coin flip; a clone changed no top-50 list in 500 test queries (DR-45).¶
A generation is served only after the labeled question set (Section 13.1) runs against it and against the generation in service, question by question. It passes when all of the following hold (DR-44):¶
Wins and losses are counted per question, with a sign test and a paired bootstrap interval. A change made only for speed must leave every ranked list identical instead (DR-06).¶
The engine never edits the index it serves. Switching to a new generation is one setting and a service restart, with a smoke test before and after; if the test after the switch fails, the engine returns to the previous generation by itself (DR-41).¶
Every search runs a keyword leg and a dense leg in parallel, fuses their rankings, reranks the best candidates with a cross-encoder, folds duplicates, and delivers the result in three tiers (Figure 4).¶
queries --+--> BM25 (FTS5) ---- 50 --+
| +--> RRF, k=60 --> top 30
+--> dense (exact) -- 50 --+ |
v
cross-encoder over top 15, 1,600-char
window centered on best-matching text
|
v
fold identical passages (also_in)
|
v
32 hits: 8 full, 8 trimmed, 16 pointers
A search_many call carries one to eight queries; the research skill sends identifiers as
keyword-only queries and paraphrases as dense queries. When a query contains identifiers, the engine also
forms a keyword variant from them and sends it to the BM25 leg only, where it improves ranking and costs no
embedding (DR-23).¶
The keyword leg uses SQLite FTS5 [FTS5] with the unicode61 tokenizer and
diacritics removed. BM25 [BM25] scores two columns, the passage text at weight 1.0 and the
heading path at weight 2.0. Ranking happens inside FTS5 and only the top 50 rows are read. Query terms that
occur in at least half of all passages are dropped before the search; a request can turn this off
(DR-22).¶
Opt-in collections live in a second FTS5 table with the same definition. BM25 statistics count every row of the table a query runs on, including rows a filter later excludes, so separate tables are what keep default rankings unaffected by opt-in documents (DR-14).¶
Embeddings come from jina-embeddings-v5-text-small [JINA-EMB], served by Text
Embeddings Inference 1.9 [TEI] on the Forge: 1024 dimensions, float32, last-token pooling,
cosine distance, with the model revision pinned. The input forms are fixed:¶
query: "Query: {text}"
passage: "Document: {title}\nSection: {section path}\n\n{text}"
¶
The Workstation searches the vectors with an exact scan (Section 8.3). A Linux engine loads the same vectors into Qdrant [QDRANT] with an HNSW index [HNSW]. My production deployment keeps HNSW, where exact search changed 17 of 726 final answers with one loss and no wins (DR-46).¶
BM25 scores and cosine similarities are on different scales, so the legs are combined by reciprocal rank fusion [RRF], which uses ranks only. With r_i(p) the 1-based rank of passage p in leg i, and w_i the leg's weight:¶
score(p) = sum over legs i that returned p of w_i / (60 + r_i(p))¶
Both legs have weight 1.0. Each leg contributes 50 candidates and the top 30 fused passages are kept (DR-21). On the test set, hit@1 is 0.710 for BM25 alone, 0.783 for dense alone and 0.822 fused.¶
A cross-encoder, jina-reranker-v3.5 [JINA-RR], reads the question together with
each of the top 15 fused candidates (10 per query inside search_many) and scores how well the
passage answers it. It reads a window of 1,600 characters centered on the candidate's best-matching lines,
not the passage head (DR-28). The reranked order replaces the fused order for those candidates.¶
Reranking is the largest single gain (hit@1 from 0.822 to 0.955) and most of a search's time: about 400 ms of a 540 ms median (DR-26).¶
Vendor documentation repeats itself across releases. Passages with identical normalized text and an
identical delivered window fold into one hit, which lists the other locations in also_in. A passage
half-covered by a better-ranked hit from the same file is dropped (DR-29). Folding happens after reranking.¶
release_max skips documents from a newer release on the same major line. prefer_release
chooses which copy of a folded passage is shown, without changing rank or text. A hit from a release other
than the preferred one is marked (DR-30).¶
By default a search returns 32 hits in three tiers: ranks 1 to 8 with up to 2,400 characters each, ranks
9 to 16 with 800, and ranks 17 to 32 as 250-character pointers (DR-31). Each window is centered on the hit's
best-matching line. A request with limit gets exactly that many hits instead. The agent reads whole
sections through get_outline and get_section; the windows exist to locate text, not to be
quoted from blindly (DR-35).¶
The Forge is often a desktop PC, so the engine treats it as unreliable (DR-32). After three consecutive
failed calls to a model service, a circuit breaker skips that service for 30 seconds and then lets one trial
call through. BM25 always answers. Every response carries a degraded list:¶
| Failure | Search behavior | degraded |
|---|---|---|
| Embedding service or vectors | BM25 alone | dense |
| Reranker | Fused order, not reranked | reranker |
| Lookup tables | Hits without RFC status | kb |
| Section index | Hits without section references | structure |
Admission is bounded (DR-33). The Workstation runs two searches at once and queues sixteen; any further request receives HTTP 503 with Retry-After. Connections to the model services stay open for 300 seconds, because a new TLS handshake across the tailnet cost 61 to 73 ms against 4 to 5 ms on a reused connection (DR-34).¶
The gateway is an MCP server using the Streamable HTTP transport with JSON responses [MCP].
It is stateless and holds no documents: it checks the bearer token in constant time and passes the call to
the engine. On the Workstation it listens on loopback and is published to the tailnet by Tailscale Serve at
https://<node>.<tailnet>.ts.net/mcp (Section 10.1).¶
All eleven tools only read (DR-73).¶
| Tool | Returns |
|---|---|
| search_rag | Ranked hits for one query, each with citation, section path, RFC status and a text window |
| search_many | One to eight queries fused into one ranked list |
| get_outline | A document's section tree, to a depth or under one chapter |
| get_section | A section's full text with its neighbors, paged up to 100,000 characters per call |
| grep_corpus | Matching lines with document, line and section; literal by default, bounded regular expressions optional |
| find_command | CLI index rows: command, mode, platform, release |
| lookup_id | What an identifier is and where it is defined |
| lookup_rfc | Status, obsoletes, obsoleted-by, updates and errata of an RFC |
| verify_quote | exact, normalized or not_found, with the location |
| list_documents | The catalog: key, type, release, RFC status, size, title |
| rag_status | Generation, fingerprint, counts, backend and breaker state |
verify_quote takes a quotation and a document, optionally a section, and returns one of three
results (DR-37):¶
The check is a string match with no model involved, so it gives the same result every time. It shows that the words are in the source; it says nothing about whether the reasoning built on them is right.¶
Given tools, a model will often still answer from memory. The research skill that ships for Claude Code and Codex therefore has the agent follow a fixed procedure (DR-40):¶
search_many call with three to six queries, restricted to one collection where the
question allows.¶
lookup_rfc on every RFC cited.¶
verify_quote on every quotation; drop any that returns not_found and reread the
section.¶
The default depth runs at most three bounded search rounds and one batch of quotation checks. Deeper modes are available on request (DR-79).¶
The Workstation is OpenBSD 8.0 on amd64 with a CDE desktop in the HP-UX style (DR-51). It installs on a physical machine or as a virtual machine: Hyper-V Generation 1, or KVM with BIOS firmware, IDE disks, a VGA display and an e1000 network adapter. Native code and Python packages are built for the plain amd64 baseline, with no processor-specific flags (DR-53).¶
The engine and gateway are the same Python programs as my production deployment, so their results are identical by construction (DR-52). They run as separate users under pledge(2) [PLEDGE] and unveil(2) [UNVEIL]; the engine listens on a UNIX socket and the gateway on loopback.¶
Securelevel 2 was tested and rejected: it broke encrypted USB media, disk formatting and connection handling.¶
Qdrant does not run on OpenBSD without Docker, so the Workstation scans vectors.f32 exactly with a
small C kernel (DR-55). The kernel uses SSE with four 128-bit accumulators and one fixed order of operations
on any amd64 processor, and refuses to be built with FMA or AVX code, so a given query produces the same
scores on every machine.¶
On a 78,275-vector index the exact scan took 12.7 ms against Qdrant's 19.8 ms. Its scores matched production's exact mode with no mismatch over 154,392 compared pairs. Qdrant's own kernel takes an AVX path when the processor has both AVX and FMA, so on such hosts the two can differ in the last bits; release acceptance therefore compares ranked hits and allows score differences below a stated tolerance. The cost of an exact scan grows linearly with the corpus.¶
The Ask window is the Workstation's client for the Ask link (Section 11), and
d32-ask sends the same requests from a terminal. The Deep32 Library
is a separate reference collection (an encyclopedia subset with media, papers and an RFC shelf) with its own
storage and indexes. The gateway's tools never search it; a document enters the corpus only when the user
sends it there and a new generation is built (DR-19). The encyclopedia's article text is from Wikipedia under
CC BY-SA 4.0, and each picture keeps its author's license. It ships as a Kiwix archive whose SHA-256 matches
the one Kiwix publishes for it.¶
The installer and first boot report progress as single-line records on the serial console (contract C6), so a host can follow an unattended install without screen scraping.¶
At first start the Workstation waits for its Tailscale sign-in. It shows the sign-in address on the text console, in a C6 record on the serial line, and in the First Start window on the desktop. Once it is signed in and has its tailnet address, it looks for disc 2 in its CD drives and imports it without further input; First Start and the console follow the import. The importer checks the signature first, then reads the disc once, in two parts, checking each file against the signed manifest as it reads it (Section 5.2). The first part is the knowledge base: it is copied, checked, installed and switched on by itself, so search, Ask, publication and pairing work from then on. The Library follows in the same run, at a lower priority, and switches on when all of it has checked out.¶
On 20 November 2026, on a KVM virtual machine reading disc 2 from a virtual CD drive, the knowledge base was in use about 8 minutes after the import started, and a complete import took about 2 hours.¶
The Forge runs the embedding and reranking models in Docker. Both listen on loopback behind one door that
checks the Forge token, and the door is published to the tailnet with Tailscale Serve (DR-63). The token is
made on the Forge and handed to the Workstation at pairing. One Linux Docker form with Compose and restart
policies runs on every host (DR-60). On Windows it runs in Docker Desktop or in an Ubuntu 24.04 WSL 2
distro with Docker Engine. Release 0.1.0-alpha.2 needs Docker's classic image store (overlay2):
its images do not load into the containerd store, which Docker Engine 29 and Docker Desktop use by
default.¶
Text Embeddings Inference builds are specific to a GPU generation, and a pack carrying every build was mostly bytes a given user would never run. The GPU pack is therefore split (DR-61):¶
Supported cards are NVIDIA compute capability 7.5 and newer, which is the RTX 20 series onward, in seven
classes: 7.5, 8.0, 8.6, 8.9, 9.0, 10.0 and 12.0 (DR-62). deep32-inventory names the class before
anything is downloaded. Older cards and other vendors' graphics get a keyword-only Workstation.¶
In 0.1.0-alpha.2 the shared core is 18.6 GB, each embedder add-on 3.1 to 3.3 GB and the ingestion add-on 15.3 GB, so a Forge downloads about 37.1 GB. The images are stored uncompressed in this release.¶
A PDF conversion job takes the whole card: it pauses the embedding and reranking services and runs one job at a time. The MinerU [MINERU] stage needs AVX2; on older processors the converter uses PyMuPDF only (DR-64).¶
Users run different GPU generations and vectors differ in the last bits. The two measured cards agree within 1e-4, and a release ships vectors computed on one card (DR-65). The Workstation's check of a paired Forge allows a cosine of at least 0.999 for an embedding and 0.005 for each rerank score, so any supported card generation passes while a wrong or damaged model fails (DR-107). Measured on an RTX 3080 and an RTX 2080 Ti over 19 known-answer queries: minimum cosine similarity between the two cards' vectors 0.999999854, 14 of 19 vectors bit-identical, largest component difference 5.9e-5.¶
Every part signs in to the user's tailnet with the user's own account, during install or, on the Workstation, at first start (Section 8.5); no image carries an auth key (DR-66). Services listen on loopback and are published with Tailscale Serve [TAILSCALE] over HTTPS, on the tailnet only. The installer adds the routes it owns, refuses to touch routes it did not add, refuses Funnel, and never changes tailnet settings itself (DR-67).¶
Serve's HTTPS certificates put machine names in the public Certificate Transparency logs [RFC9162]. Default machine names carry nothing personal, and publication asks for explicit agreement once.¶
Parts should reach each other directly. A relayed path measured 70 to 157 ms against 1 to 2 ms direct, and
deep32 doctor reports a relayed path as a warning (DR-70).¶
Every token is 32 random bytes written as 64 hexadecimal digits. Each is made on the machine whose service checks it, at first boot or at pairing, and kept where only that service can read it. No token appears on an image, in a log or in a status line (DR-68).¶
| Credential | Made on | Used for |
|---|---|---|
| Engine token | Workstation | Gateway to engine |
| MCP token, one per paired agent | Workstation | Agent to gateway |
| Forge token | Forge | Engine to the Forge's door |
| Forge bundle key | Forge | Signs bundles the Forge builds |
| Link certificates and pins | Each end of a link | Mutual TLS |
The Workstation pairs with a Forge, and an agent pairs with the Workstation's gateway, by the same procedure (DR-69). The side being joined is the responder; the other side is the joiner.¶
[A-Z2-7]{10}, normally in two groups of five. The window lasts five minutes and allows
one attempt.¶
Three failed windows within 30 minutes lock pairing for 15 minutes. The window deadline uses a monotonic clock; the lockout uses wall-clock timestamps that survive a restart. Removing a pairing on either side revokes what that side gave.¶
With transport=loopback, every service is reached on 127.0.0.1 and sign-in, Serve and discovery
are skipped. Tokens and pairing still apply, so every test runs on one machine with no tailnet (DR-71).¶
The Ask link carries research sessions between the Workstation and the relay. The Workstation's side of the protocol is the C link client that has shipped on the Workstation since before this release; the portable relay implements the other side. This section states the protocol as that client implements it.¶
The Workstation (role node) dials a TCP connection to the relay (role relay). The relay
binds loopback and is reached across the tailnet through a TCP forwarder that its installer creates.¶
Both ends use mutual TLS 1.3 [RFC8446]; TLS 1.2 is allowed only by explicit local configuration, and there is no plaintext form. Each end has a self-signed X.509 v3 certificate [RFC5280] with an ECDSA P-256 key, valid for ten years. The trust anchor is the pin: the SHA-256 of the peer's whole DER certificate. Chain, host name and validity-period checks are not used. A peer whose certificate does not match the stored pin MUST be refused, except during an armed pairing window (Section 11.5).¶
Every frame has a 12-byte header (Figure 5). All integers are unsigned and big-endian.¶
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Payload Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Stream ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type | Channel | Flags | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Payload (variable) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Type | Name | Payload |
|---|---|---|
| 1 | HELLO | JSON, at most 16,384 bytes |
| 2 | HELLO_ACK | JSON, at most 16,384 bytes |
| 3 | OPEN | JSON, at most 16,384 bytes |
| 4 | OPEN_ACK | Empty |
| 5 | DATA | Non-empty |
| 6 | WINDOW_UPDATE | 4-byte credit |
| 7 | CLOSE | Empty |
| 8 | RESET | 4-byte error code |
| 9 | PING | 8 opaque bytes |
| 10 | PONG | The 8 bytes of the PING it answers |
| 11 | ERROR | 4-byte error code |
| 12 | PAIR_CONFIRM | Empty |
| 13 | PAIR_COMMIT | Empty |
Type 0 and types above 13 are protocol errors.¶
After TLS completes, the node sends HELLO with a fresh 32-byte nonce. The relay answers with its own HELLO and then, after the node's HELLO_ACK, its HELLO_ACK. The node's HELLO is:¶
{"proto":"D32U/1","id":"workstation","version":1,"versions":[1],
"role":"node","features":["research-v1"],
"nonce":"<64 lower-case hex digits>","sessions":[]}
¶
The relay's HELLO has the same members with role relay, and may add profiles: a list of
at most one entry, named research, that lists the models and the strengths (efforts) the
relay offers. Each entry in those lists is a string of at most 64 bytes, and the node keeps at most 16 of
each. HELLO_ACK is
{"version":1,"features":["research-v1"],"paired":true}, or false for
paired. When both acknowledgements say paired, the link is active. Messages are strict UTF-8 JSON
[RFC8259]: no byte order mark, no duplicate keys, no unknown keys, nesting at most 32 deep.
Reconnecting does not resume sessions; the sessions array is always empty.¶
| Channel | Opened by | Carries |
|---|---|---|
| 1 | Node | Research sessions: questions, streamed answers |
| 2 | Relay | Reverse MCP: the agent's tool calls to the Workstation's gateway |
| 4 | Relay | Relay status |
An OPEN on any other channel receives RESET. The node allocates odd stream IDs from 1 and the relay even ones, each increasing and never reused on a connection.¶
A research session starts with a session.open message, the first DATA on a new channel 1 stream.
It names the model and the strength chosen for the conversation, from the lists in the relay's HELLO; the
relay turns away a model or a strength it did not offer.¶
Each stream starts with 256 KiB of credit, replenished by WINDOW_UPDATE. Each side sends PING every 15 seconds while active and drops the link after 45 seconds without a valid complete frame; a sender waits at most 180 seconds for credit. A side sends at most 256 frames per second, counting control frames. The node reconnects with backoff of 1, 2, 4, 8, 16 and 30 seconds, each multiplied by a random factor between 0.8 and 1.2, and only to a pinned peer.¶
The Ask link does not use the short code of Section 10.3. It keeps the comparison that its Workstation client already implements; replacing it would have meant a Workstation protocol change for no security gain (DR-69).¶
D = SHA-256(P_lo || P_hi || N_node || N_relay)¶
A stored pin is replaced only by removing the pairing first. Removing it deletes the pin, ends the link and ends every session on it.¶
The agent in an Ask session reaches the gateway through the link. The relay runs a loopback proxy for each session with its own random bearer, and forwards a call only while a verified turn is running. Each call travels on channel 2 to the Workstation, which passes it to its gateway on loopback. The headend never dials the Workstation's published gateway for an Ask session.¶
An agent started by the relay can call the eleven tools of Table 6 and nothing else (DR-76): no shell, no file reads or writes outside an empty per-session folder, no web access, no other MCP server, and none of the user's own configuration, skills or MCP entries.¶
During a turn the relay reads the agent's output as a stream of typed events and keeps only the answer
text, the final result and the turn's token counts. A call to any tool outside the eleven, or an event of a
kind the relay does not know, ends the turn with an error. Claude Code's report of its usage window between
messages (rate_limit_event) is a known kind: it carries no answer text and does not end the turn.
A turn whose final result is an error still fails. When Claude Code's profile has no usable sign-in at the
start of a session, or the model provider refuses the sign-in during a turn, the relay stops with the reason
agent-sign-in-required and does not pass the agent's error line on as an answer.¶
At install and after each sign-in, the relay runs an install check that uses no model. It starts the agent as far as its initialization report, records the agent's version, the model and strength it starts with and the models and strengths it lists, and stops it before any question. The record is bound to the SHA-256 of the agent program, so after an agent upgrade the relay refuses Ask sessions until the check has run again.¶
A live self-test goes further: scripted attempts to escape the box (run a command, write outside the session folder, fetch a web page, reach another MCP server, read the user's agent configuration) must all fail, and one allowed tool call must succeed. Each attempt uses the user's model allowance, so it runs only when the user asks for it.¶
The images are whole files hosted on the Internet Archive [IA], which also serves an official torrent of each. The GitHub release holds the signed metadata: a root checksum list and its detached signature, a mirror list, an asset map, one child checksum list per image, each image's README and its software bill of materials (DR-90). A mirror is untrusted transport; trust comes only from the root list's signature.¶
Release metadata is signed with one long-lived OpenPGP key [RFC9580] (Ed25519) as a detached, armored, binary-mode signature (DR-86). The key's fingerprint is pinned in the repository and printed in the README. Each verifier runs GnuPG with a new, empty home directory and only the release key shipped with it, so the user's own keyring is never used. There are two verifiers:¶
deep32-get and verify-release in src/release-tools, in their shell
and PowerShell forms, share one Python helper that runs gpg. The helper refuses a key file that
holds a secret key or does not hold exactly one primary key with the pinned fingerprint, imports that key
alone, and runs
gpg --verify on the root checksum list; verify-release also verifies each image's child
list the same way. A signature is good only when all of the following hold:¶
The disc 2 importer runs gpgv with a keyring holding only the release key installed with
the system. A signature is good only when gpgv exits 0, its status output has exactly one GOODSIG
and one VALIDSIG and none of BADSIG, ERRSIG, EXPSIG, EXPKEYSIG, REVKEYSIG or NO_PUBKEY, the signature class
in VALIDSIG is 00, and its primary-key fingerprint equals the pinned fingerprint.¶
Nothing in the metadata is parsed before the signature is good. The verifier then parses the same bytes it verified, never a re-serialized copy.¶
deep32-get downloads an image as follows:¶
If every mirror fails, the getter prints the torrent URL from the signed metadata as a manual alternative; it contains no torrent client.¶
Each image has an SPDX 2.3 [SPDX] document beside it, covered by the root list. Keeping the bills of materials outside the images left disc 2 byte for byte the image that had already passed the release gates (DR-95).¶
The release notes state only the reproducibility that was demonstrated: which artifacts were built twice and compared byte for byte. Appendix C gives the state for this release.¶
deep32 doctor checks every link of an installation without changing anything, prints one row per
check with OK, WARN or FAIL, and prints a suggested fix next to each failure (DR-94).¶
deep32 selftest runs a public question set through the installation and compares retrieval with
the release's reference values. The set has 63 RFC-only questions, nine in each of seven topics (BGP, BGP
extensions, OSPF, IP, MPLS, segment routing, and other protocols), balanced across natural-language, keyword
and identifier styles. Its 107 labels each name a document and an exact span of that document's shipped
text. A question counts as found at the rank of the first of its first ten hits whose document matches a
label and whose text contains that label's span. The tool reports hit@1, hit@3, hit@8 and MRR@10. The
reference values come from three identical runs on the release host.¶
The test set has 726 questions: 696 whose answer is in the corpus and 30 whose answer is not (DR-98). They cover enterprise routing, switching, VPN, SD-WAN, network services and access control, with at least three answerable questions per topic.¶
Questions and first labels were written per topic by an LLM pipeline with an author and an adversarial verifier. After each corpus change, newly retrieved passages are judged in pools and audited blind; the last two audits agreed on 22 of 27 and 15 of 16 items. Labels are copied to identical passages in sibling documents (DR-99). There are 9,209 labeled spans across 463 documents. Evaluation data is never ingested into the corpus (DR-103).¶
Every comparison is paired by question: wins, ties and losses, a sign test, a paired bootstrap interval and a per-topic breakdown (DR-101). Three runs over one week returned identical metrics.¶
All 696 answerable questions, through the gateway, on 2 November 2026:¶
| Stage | hit@1 | hit@8 | Median ms |
|---|---|---|---|
| BM25 only | 0.710 | 0.928 | 125 |
| Dense only | 0.783 | 0.970 | 122 |
| Fused | 0.822 | 0.983 | 140 |
| Fused and reranked | 0.955 | 0.991 | 542 |
| Metric | Fused and reranked | Fused only |
|---|---|---|
| hit@1 | 0.955 (665) | 0.822 (572) |
| hit@3 | 0.983 | 0.934 |
| hit@8 | 0.991 (690) | 0.983 (684) |
| MRR@10 | 0.970 | 0.882 |
| delivery@8 | 0.909 | 0.904 |
Paired over the 696 questions, reranking wins 102 and loses 9 at hit@1, and wins 6 and loses none at hit@8.¶
Each of the 31 questions missed at rank 1 was judged afterwards. In 7, the rank-1 passage did answer the question but had no label. In 21, the reranker placed another passage above a relevant one. In 3, fusion left the relevant passage outside the reranker's top 15. With the 7 label gaps corrected, hit@1 would be 0.966 (672 of 696). I report 0.955 until the label set is frozen again (DR-100).¶
The model provider sees each question, the passages the agent reads and the agent's reasoning. A user who cannot send those to a provider cannot use Deep32 as released. A slot for a locally served, OpenAI-compatible model exists in the adapter interface with no adapter behind it yet (DR-77).¶
Tokens are generated on the machine that checks them and never leave it except inside an authenticated pairing. Agent credentials are held by the operating system's protected store (DPAPI for the current user on Windows; a mode 0600 file in a mode 0700 directory on Linux) and loaded into the agent's process only. They never appear in an MCP configuration file, an argument list or output (DR-78). The gateway compares bearer tokens in constant time.¶
A pairing code has 50 bits of entropy and is never sent. SPAKE2 gives an attacker who observes or intercepts an exchange no way to test guesses offline, so each guess has to be made online and costs a whole pairing window. Only a person at the responder's console can open a window, each allows one attempt, and three failed windows in 30 minutes lock pairing for 15 minutes. The person sees every failed window.¶
The Ask link's string has 110 bits and depends on both certificates and both nonces. An attacker in the middle would have to make both sides display the same ten words for two different certificate pairs. Typing the other side's words, rather than glancing at both, keeps a person from approving a mismatch by habit. Unknown certificates are accepted only while a window armed on that side's own console is open.¶
Services listen on loopback. The only routes into a part are the Serve routes its installer owns and, on the headend, the relay's forwarder. Funnel is refused, so nothing is published to the public Internet. The Workstation's pf permits outbound traffic only to Tailscale's infrastructure, to time servers and to Let's Encrypt, which Tailscale uses to issue the HTTPS certificate for a published service. Machine names appear in Certificate Transparency logs once HTTPS certificates are issued.¶
Documents can carry text written to steer a model. Ingest flags instruction-like lines for review, and the gateway's server instructions tell the agent that tool output is document text, never instructions (DR-11, DR-74). Both are mitigations; a model can still follow injected text. The agent box limits what an Ask session can do if it does: it can only search and read the corpus.¶
Every image is checked against signed metadata before use, and a mirror cannot substitute content (Section 12). Model files and container images in the GPU pack are pinned by digest, and the SPDX documents list what each image contains. The release is built from pinned sources through an allowlist, then rebuilt and scanned as its own product, because built files can carry strings from material that was cut (DR-82, DR-83). Whoever holds the release signing key can sign a malicious release; the key is held by the author alone.¶
On the Forge, membership in the docker group is equivalent to root, as on any Docker host. On
the Workstation, system files are immutable at securelevel 1, so a
compromised service cannot replace them without a reboot into the boot window. Admission control
(Section 6.9) keeps a burst of searches from exhausting the engine's worker threads.¶
In this release Ask has no password of its own (DR-111). Root and every account in the Workstation's
_d32users group can open the Ask broker's socket, from the Ask window or a terminal, and ask
questions on the plan of the agent signed in on the relay. The pairing (Section 11.5) and the
tailnet protect the link to the relay; who can ask on the Workstation itself is decided by its accounts,
its login and its screen lock.¶
This document has no IANA actions.¶
Where to find the reasons behind each part of this report in the Decision Record [D32-DR].¶
| Section | Decisions |
|---|---|
| 1, Introduction | DR-01 to DR-08, DR-110 |
| 4, Corpus | DR-09 to DR-19 |
| 5, Index Generations | DR-36, DR-41 to DR-49 |
| 6, Retrieval Pipeline | DR-20 to DR-35 |
| 7, Agent Interface | DR-37 to DR-40, DR-73, DR-74, DR-79, DR-80 |
| 8, Workstation | DR-50 to DR-57 |
| 9, Forge | DR-58 to DR-65, DR-106 to DR-108 |
| 10, Network and Pairing | DR-66 to DR-72 |
| 11, The Ask Link | DR-69, DR-75, DR-76, DR-111 |
| 12, Distribution | DR-81 to DR-97 |
| 13, Evaluation | DR-98 to DR-105 |
deep32 doctor, deep32 selftest, SPDX documents beside each image (DR-94,
DR-95).¶
e26-render, which use MuPDF, stay under AGPL-3.0-or-later (DR-110).¶
The table compares what this report specifies with what release 0.1.0-alpha.2 does, in the places where the two differ or where the release has not been tested in full.¶
| Section | Specified | In this release |
|---|---|---|
| 10.1, 12.5 |
deep32 doctor checks every link of an installation and reports a relayed path as a
warning |
On the images, but not working yet: it does not read an installation's record, so it always reports the installation check as failed |
| 12.5 |
deep32 selftest compares retrieval
with the release's reference values |
The reference values are not shipped |
| 10.3 | Removing a pairing on either side revokes what that side gave | Revoking a pairing on the Forge leaves the Forge unable to restart; revoke by reinstalling the Forge into a new data folder |
| 11 | The Ask link carries research sessions between the Workstation and the relay | Works end to end with Claude Code on the relay: a question asked on a
Workstation, in the Ask window or with d32-ask in a terminal, is answered through the relay. The
Ask window has no password of its own in this release, so every account in the Workstation's
_d32users group can ask (DR-111, Section 14.7) |
| 3.1, 8.1, 9.1 | The three parts share a machine or sit on three; the Workstation runs on a physical machine, in Hyper-V or in KVM; the Forge runs on Linux or on Windows | A Workstation in a KVM virtual machine with a Forge on Linux is the tested layout; the all-in-Docker layout, which runs the engine and gateway in containers on the GPU host with no Workstation, is not in this release's images; a Hyper-V Workstation and a Docker Desktop Forge have not been run end to end |
| 12.4 | The release notes state which artifacts were built twice and compared byte for byte | The disc 2 build writes its image twice and stops unless the two copies are identical. The GPU pack's producer stages and writes the shared core image twice from the same inputs and stops unless the two images are byte-identical. Disc 1, the embedder add-ons and the ingestion add-on were each built once, and no byte comparison of them is published |
| 9.1 | One Docker form runs on every Forge host: Linux, an Ubuntu 24.04 WSL 2 distro and Docker Desktop | Forge host acceptance has not been run in full; the install is opened by my waiver as release owner, and full runs on Linux, WSL 2 and Docker Desktop follow in a signed revision |
| 9.2 | The capability manifest in the signed metadata gives a storage budget for each GPU pack component | The budgets are declared upper bounds until they are measured |
| 9.3 | The Forge converts a PDF with MinerU, or with PyMuPDF alone on a processor without AVX2 | On 19 November 2026 this release's ingestion image
converted a one-page test PDF with --tier standard on an RTX 2080 Ti in about 2 minutes 22
seconds, with Docker Engine 29.1.3 in an Ubuntu 24.04 WSL 2 distro. A conversion with the default
--tier advanced, or in Docker Desktop, has not been run |
Deep32 is built on the work of others: OpenBSD, SQLite, Qdrant, Text Embeddings Inference, the Jina AI embedding and reranking models, MinerU, MuPDF, PyMuPDF, Tailscale, and the RFC Editor's archive of the RFC series. Their licenses are listed in the repository's notices.¶