TrustedRouter Field Manual
Onboarding · 0 → CTO

TrustedRouter Field Manual

A complete onboarding pack for quill-router and the Lore-Hex org: setup, architecture, money, data, infra, security, the ecosystem, and the leadership view.

Hour 1

Orientation

  1. Start here
    The 0-to-CTO path, what TrustedRouter is, and how to use this pack.
  2. System teardown
    A clickable map of the whole system, plus the codebase in numbers.
  3. Explainer videos
    Six Manim animations: big picture, request lifecycle, setup, config, contributing, deploys.
Day 1

Run it, change it

  1. Local setup & config
    Verified Day-1 setup on macOS plus the full environment variable reference.
  2. Contributing & tests
    The three CI gates, test taxonomy, PR conventions, and your first PR.
Week 1

Understand the system

  1. Architecture
    Subsystem map and the end-to-end lifecycle of a chat completion.
  2. Product surface & docs
    Every API surface, provider, script, and doc in the repo, indexed.
  3. Security & trust
    Attestation, the trust boundary, privacy tiers, keys and BYOK.
Month 1

Own the risky parts

  1. Money & billing
    Credits, reserve/settle/refund, async settlement, and payment rails.
  2. Data & storage
    The Store protocol, Spanner, Postgres, ClickHouse, and multi-cloud.
  3. Infra & deploys
    CI/CD, rollout.sh, Terraform, clouds, observability, runbooks.
Ecosystem

Know the whole org

  1. Platform repos
    quill-cloud-proxy and the other infrastructure repos in Lore-Hex.
  2. SDKs, apps & benchmarks
    Every SDK, integration, app, and benchmark repo in the org.
Leadership

Run engineering

  1. The CTO view
    History, velocity, risk register, and a 30/60/90-day plan.

Open the print handbook (PDF, 185 pages): every chapter, diagram, and storyboard from this site, laid out for reading offline.

What this is

TrustedRouter is an OpenAI- and Anthropic-compatible LLM router whose prompt path runs inside hardware-attested Confidential Space. Clients can check the running binary against the public source with a nonce. quill-router is the Python/FastAPI control plane: auth, keys, routing policy, the credit ledger, billing, usage metadata, and the website. The attested gateway lives in quill-cloud-proxy.

This manual was produced by a parallel deep read of the repository and the Lore-Hex GitHub org. Every chapter cites path:line so you can jump into the code. Diagrams render from Mermaid source; open "Diagram source" under any figure to copy it.

Five rules to know before touching anything

  1. Run all three gates before claiming done: uv run ruff check . && uv run mypy && uv run pytest -q. Never run ruff format ..
  2. Pushing to main auto-deploys the control plane to Cloud Run when src/**, deploy scripts, the Dockerfile or the lockfile change.
  3. Runtime config is code: the ENV_VARS array in scripts/deploy/rollout.sh. Hand-set Cloud Run vars are overwritten.
  4. Reserve, settle, refund and credits need a differential or conformance test, not review by eye.
  5. Read-only is not load-safe. Never scan production tr_entities.body with LIKE, regex or JSON predicates.