Start here · TrustedRouter Field Manual
Orientation

Start here

The 0-to-CTO path, what TrustedRouter is, and how to use this pack.

Video 01 The big picture · Clients, the attested gateway, the control plane, providers, and the trust boundary.

TrustedRouter in one paragraph

TrustedRouter (Lore Hex Corp) sells one OpenAI- and Anthropic-compatible API in front of 100+ model providers. The claim that sets it apart: the code path that touches your prompt runs in hardware-attested confidential VMs, and you can verify with a nonce that the running binary is the published source. Customers point their SDK at https://api.trustedrouter.com/v1, pick a privacy floor (min_privacy: zdr or confidential) and a model, and pay from prepaid credits.

The three planes

Most onboarding confusion comes from not knowing which plane a piece of code lives in.

flowchart LR
  C["Client / SDK"] -->|"prompt over TLS"| G
  subgraph TEE["Attested gateway: api.trustedrouter.com (quill-cloud-proxy, Go)"]
    G["Gateway in Confidential Space / Nitro / SEV-SNP"]
  end
  G -->|"prompt"| P["Providers: OpenAI, Anthropic, Gemini, Tinfoil, ..."]
  G -->|"metadata only: key hash, model, token counts"| CP
  subgraph CPL["Control plane: trustedrouter.com (quill-router, Python/FastAPI, Cloud Run)"]
    CP["authorize / settle / refund, routing policy, catalog, billing, console"]
  end
  CP --> S[("Spanner: credits, keys, reservations, outboxes")]
  S -->|"outbox drain"| CH[("ClickHouse: analytics")]
  CP -.->|"pilot: regional credit leases"| FP["fastpath (Go)"]
Diagram source
flowchart LR
  C["Client / SDK"] -->|"prompt over TLS"| G
  subgraph TEE["Attested gateway: api.trustedrouter.com (quill-cloud-proxy, Go)"]
    G["Gateway in Confidential Space / Nitro / SEV-SNP"]
  end
  G -->|"prompt"| P["Providers: OpenAI, Anthropic, Gemini, Tinfoil, ..."]
  G -->|"metadata only: key hash, model, token counts"| CP
  subgraph CPL["Control plane: trustedrouter.com (quill-router, Python/FastAPI, Cloud Run)"]
    CP["authorize / settle / refund, routing policy, catalog, billing, console"]
  end
  CP --> S[("Spanner: credits, keys, reservations, outboxes")]
  S -->|"outbox drain"| CH[("ClickHouse: analytics")]
  CP -.->|"pilot: regional credit leases"| FP["fastpath (Go)"]
Plane Repo Sees prompts? Owns
Attested gateway Lore-Hex/quill-cloud-proxy Yes, and only here TLS termination in the TEE, provider calls, streaming, fallback, attestation endpoint
Control plane Lore-Hex/quill-router (this repo) No in production; inference routes mount only in local/test Auth, keys, routing policy, catalog and pricing, credit ledger, payments, website, console
Fastpath quill-router/fastpath/ No Pilot admission against regional credit leases, running for two workspaces

The numbers, as of 2026-10-19

Metric Value
First commit 2026-05-03 (production the same day)
Commits / merged PRs 3,213 / about 1,711
Python source / tests about 194k / 343k lines (1.77 test lines per source line)
Test files / tests 855 files, about 36.7k tests, sharded 12 + 8 + 6×2 in CI
Top-level modules in src/trusted_router 371, of which about 98 are the async-settle shadow program
Store protocol methods 210 (AGENTS.md still says about 97)
Providers in catalog 108
GitHub workflows 28
Incidents written up since Sep 5 25
Human committers effectively one architect plus one front-end engineer; most code is written by Codex and Claude agents

How to use this manual

Follow the track in the left rail. Each stage assumes the one before it.

  1. Hour 1. Read this page, then watch the six explainer videos (about 8 minutes in total).
  2. Day 1. Local setup & config gets the app running on your Mac with verified commands. Contributing & tests covers the three CI gates and how a PR reaches production.
  3. Week 1. Architecture shows where each module fits. Product surface maps every endpoint and doc. Security & trust explains what the attestation claim proves and what it does not.
  4. Month 1. These are the high-risk areas. Money & billing, Data & storage, Infra & deploys.
  5. Ecosystem. Platform repos (start with quill-cloud-proxy) and SDKs, apps & benchmarks.
  6. Leadership. The CTO view covers history, velocity, the risk register, and a 30/60/90-day plan.

Rules that will bite you on day one

Rule Why
uv run ruff check . && uv run mypy && uv run pytest -q before claiming done These are CI's three gates. mypy is a real gate.
Never run ruff format . CI only checks. Formatting the tree produces a huge unrelated diff.
Patch backend classes in tests, never the STORE proxy monkeypatch.setattr(STORE, ...) once broke 136 later tests (issue #333).
Rebase before trusting a failure An hourly price bot commits to main.
Merging to main deploys Path-filtered on src/**, scripts/deploy/**, frontend/src/**, Dockerfile, lockfile.
Config is code Cloud Run env comes from ENV_VARS in scripts/deploy/rollout.sh. Hand edits are overwritten.
Money changes need differential tests reserve/settle/refund. Run the proof_oracle marker explicitly.
Read-only is not load-safe No LIKE/regex/JSON scans on tr_entities.body. Use python -m scripts.inspect_payment_owner.
Merging under infra/ applies Terraform There is no plan gate, and it can revert hand edits.

Where the repo's own docs are out of date

The research agents found these discrepancies. Trust the code over the doc until the doc is fixed.

Doc claim Reality Source chapter
AGENTS.md: Store has about 97 methods 210 in store_protocol.py Data
README: activity data in Bigtable, store-backed rate limits Bigtable retired 2026-09-28; Spanner outbox feeds ClickHouse; rate limits are per process Architecture
README attestation snippet pipes to jq, reads image_digest and pcrs The endpoint returns a JWT; the digest is at submods.container.image_digest; GCP has no PCRs Security
Runbook: deploy locks expire after 90 minutes cloud_rollout.py never reclaims a lock on age alone Infra
docs/spanner-reliability.md: fixed processing units Terraform now uses the autoscaler Data
docs/security.md: trust.trustedrouter.com is the control plane Signed bundles publish from the gateway repo to GitHub Pages Security
HANDOFF items 4.2–4.4 Obsolete since the Bigtable retirement Data

Rebuilding this manual

The source lives in ~/Code/trustedrouter/trustedrouter-onboarding/:

cd ~/Code/trustedrouter/trustedrouter-onboarding
uv run --no-project --with markdown python build.py     # research/*.md -> site/
python3 -m http.server 8765 --directory site             # http://localhost:8765

Edit any chapter in research/, rebuild, and refresh the page. Manim scene sources are in manim/, and its README gives the render commands.