Local setup & config

Verified Day-1 setup on macOS plus the full environment variable reference.

Every command below was run on a real Mac by the research agent on 2026-10-19 against main @ 778120494: macOS 26 (Darwin 25.6.0) on Apple Silicon, uv 0.11.6, Node v24.14.1, Docker CLI 29.6.1. ✅ = ran and passed exactly as written. ⚠️ = problem found; details are given next to it. The repo stayed clean (git status empty) after every step.

0. TL;DR (copy-paste, ~2 minutes on a warm machine)

cd quill-router
uv sync                                   # ✅ ~10 s (238 packages resolved)
uv run ruff check . && uv run mypy        # ✅ ~0.5 s + ~8–10 s
uv run pytest -q -x tests/conformance -k memory   # ✅ fast memory-backend contract
uv run uvicorn trusted_router.main:app --port 18080 --reload   # ✅ starts in about 1 s

You do not need a .env, cloud credentials, Docker, or provider keys to run the app or most of the test suite. The defaults are local-safe: TR_ENVIRONMENT=local, TR_STORAGE_BACKEND=memory and TR_ENABLE_LIVE_PROVIDERS=false, so providers are mocked.

1. Prerequisites

Install hints (macOS):

curl -LsSf https://astral.sh/uv/install.sh | sh     # uv
brew install node@20   # or nvm install 20
# Docker Desktop / OrbStack / colima: only if you will run postgres/spanner conformance

2. Python environment

uv sync

✅ Result: Resolved 238 packages, installed the dev group (the default) into .venv/. Time: 9.8 s wall-clock with a warm uv cache. A second run takes 19 ms (Checked 214 packages).

Notes * The dev dependency group includes docling and sec-parser, which pull a large ML stack (torch, transformers). A cold-cache first sync therefore downloads a lot more than the production image needs. Production uses uv sync --frozen --no-dev. * CI runs uv sync --frozen. Use --frozen too if you want to be sure you are not silently changing uv.lock. * Do not pip install into the venv by hand. uv run re-syncs to the lockfile.

3. The three CI gates (from AGENTS.md: "run all three before claiming done")

uv run ruff check . && uv run mypy && uv run pytest -q

Rules worth tattooing (AGENTS.md): * Never run ruff format .. CI only runs ruff check, and formatting produces a huge unrelated diff. * Coverage must stay ≥ 70 %. CI shards the suite with pytest-split and runs -n 4 --dist loadgroup. * The default addopts deselects proof_oracle (over an hour of differentials) and provider_health (live provider state). If you touch async settle or billing, run the oracle explicitly: uv run pytest -q -n 4 -m proof_oracle tests/test_async_settle_proof_oracle.py. * CI's lint job also runs uv run python scripts/update_model_changes.py --check. ✅ It exited 0 here.

3a. Fast, targeted pytest runs (what to use during the inner loop)

# Storage contract against the in-memory backend (postgres/spanner params auto-skip without DSNs)
uv run pytest -q -p no:cacheprovider -x \
  tests/conformance/test_store_semantics.py tests/conformance/test_key_management.py -k memory

✅ 90 passed, 14 skipped, 416 deselected, 6 warnings in 1.07s (10 s wall-clock including uv and imports)

uv run pytest -q -p no:cacheprovider tests/test_billing.py tests/test_inference_errors.py

✅ 82 passed, 142 warnings in 7.72s

uv run pytest --collect-only -q        # count / sanity-check collection

✅ 29 s

Tips * -n 4 (xdist) is available for bigger subsets. * tests/conftest.py forces TR_STORAGE_BACKEND=memory, and the operator keys file is ignored under pytest unless TR_ALLOW_LOCAL_KEY_FILE_IN_TESTS=1. Tests are hermetic by default. * Pollution trap (issue #333): never monkeypatch.setattr(STORE, ...). STORE is a __getattr__ proxy. Patch the backend class instead. Run the full suite before you merge. * The warnings you will see are FastAPI on_event deprecation notices. They are harmless.

4. Run the app locally and exercise it end-to-end

uv run uvicorn trusted_router.main:app --port 18080          # add --reload while editing

✅ Log output:

INFO:     Started server process [9685]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:18080 (Press CTRL+C to quit)

Ready in under 1 s. (Production instead runs python -m trusted_router.serve, which reads PORT, WEB_CONCURRENCY/UVICORN_WORKERS, UVICORN_PROXY_HEADERS, UVICORN_FORWARDED_ALLOW_IPS and UVICORN_TIMEOUT_KEEP_ALIVE, and keeps the listener open briefly after SIGTERM.)

4a. Health and catalog ✅

curl -s localhost:18080/health            # {"status":"ok"}   200, ~2 ms
curl -s localhost:18080/v1/health         # {"status":"ok"}   200
curl -s localhost:18080/v1/models/count   # {"data":{"count":692}}
curl -s localhost:18080/v1/models | jq '.data[:5][].id'
# "trustedrouter/auto" "trustedrouter/free" "trustedrouter/cheap" "trustedrouter/fast" "trustedrouter/green"

/, /docs, /status and /openapi.json all return 200. /healthz is not a route. It returns a markdown-flavoured 404 that points agents at llms.txt and sitemap.xml.

4b. Local auth: no OAuth needed ✅

In local/test you can act as any user by sending the x-trustedrouter-user header (this is what scripts/smoke_e2e.py and the tests do). The first call auto-creates a "Personal Workspace".

B=http://127.0.0.1:18080/v1
H='x-trustedrouter-user: dev@example.com'
curl -s $B/workspaces -H "$H"
KEY=$(curl -s -X POST $B/keys -H "$H" -H 'content-type: application/json' \
      -d '{"name":"local dev"}' | jq -r .key)          # sk-tr-v1-...

4c. Fund the workspace, then chat ✅ (the non-obvious bit)

A brand-new local workspace has $0, so the first chat returns 402 {"error":{"code":402,"message":"Insufficient credits","type":"insufficient_credits"}}. Trial credit is only granted on the OAuth/email signup paths. With no TR_STRIPE_SECRET_KEY, /billing/checkout returns a "mode":"mock" session, and in local/test the Stripe webhook accepts unsigned JSON. So you can credit yourself like this:

WS=$(curl -s $B/workspaces -H "$H" | jq -r '.data[0].id')
curl -s -X POST $B/internal/stripe/webhook -H 'content-type: application/json' -d "{
  \"id\":\"evt_local_1\",\"type\":\"checkout.session.completed\",
  \"data\":{\"object\":{\"amount_total\":2500,\"payment_intent\":\"pi_local_1\",
  \"payment_status\":\"paid\",\"metadata\":{\"workspace_id\":\"$WS\"}}}}"
# {"data":{"credited":true,"credited_microdollars":25000000,"event_id":"evt_local_1",...}}
curl -s $B/credits -H "$H"     # available: 25.0

(The event is idempotent by id. Change evt_local_N to top up again.)

curl -s $B/chat/completions -H "authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"model":"trustedrouter/auto","messages":[{"role":"user","content":"hello"}]}'

✅ Response (trimmed):

{"object":"chat.completion","model":"z-ai/glm-5.3-flash",
 "choices":[{"message":{"role":"assistant","content":"TrustedRouter response from z-ai/glm-5.3-flash."},"finish_reason":"stop"}],
 "usage":{"prompt_tokens":1,"completion_tokens":11,"total_tokens":12},
 "trustedrouter":{"content_stored":false,"requested_model":"trustedrouter/auto","selected_model":"z-ai/glm-5.3-flash","rollover_failures":[]}}

Streaming ("stream":true) ✅ emits an event: trustedrouter.route SSE frame and then standard chat.completion.chunk deltas. GET /v1/activity?group_by=none ✅ shows the metadata-only row (cost_microdollars: 3, no prompt content).

How the fake provider works: services/inference.py builds ProviderClient(LocalKeyFile(settings.local_keys_file), live=settings.enable_live_providers). With live=False (the default, and also in production, where real inference happens in the attested gateway, quill-cloud-proxy), providers.py returns mock_text(model.id) → "TrustedRouter response from <model>." No network calls are made. Set TR_ENABLE_LIVE_PROVIDERS=true and put real keys in the keys file (section 6) to call real upstreams from your laptop.

Other observations: * No auth → 401 Missing Authentication header ✅ * cerebras/llama3.1-8b → 400 model_not_supported. That model is no longer chat-capable in the catalog (see T3).

Stop the server with Ctrl-C (or pkill -f "uvicorn trusted_router.main:app").

4d. scripts/smoke_e2e.py ⚠️ stale

TR_SMOKE_BASE_URL=http://127.0.0.1:18080/v1 uv run python scripts/smoke_e2e.py

⚠️ E2E smoke failed: expected 54 OpenRouter route classifications, got 95. The script (last touched 2026-05-04) hard-codes 54 coverage rows and uses cerebras/llama3.1-8b. It also assumes new workspaces have credit. Treat it as reference reading, not a working check. Use the curl flow above instead.

5. Frontend / npm

Root package.json (trusted-router-frontend). The dashboard TypeScript in frontend/src/ compiles into committed JS under src/trusted_router/static/.

First-time browser install: npx playwright install chromium ✅ (CI uses --with-deps chromium).

tests-e2e/ is a separate npm project (its own package.json and playwright.config.ts) for the /chat playground, with 19 specs. It mocks /v1/chat/completions via page.route():

cd tests-e2e && npm install && npm run install:browsers   # chromium webkit firefox
npm test -- --project=chromium      # also: test:headed, test:debug, test:ui

(Not run by this agent. The README says the server auto-starts via webServer.)

6. Configuration: how settings are resolved

All runtime config lives in one Pydantic Settings class: src/trusted_router/config.py::Settings (2,388 lines, 354 fields). It is built by get_settings() (no caching side effects).

• env_prefix="TR_": field storage_backend ↔ env TR_STORAGE_BACKEND.
• env_file=".env" (relative to the CWD, gitignored). .env.example is the template.
• extra="ignore": unknown TR_* vars are silently ignored, so a typo does nothing.
• hide_input_in_errors=True: validation errors don't echo secret values.
• Validators fail closed. For example, TR_ENVIRONMENT=production alone refuses to start: TR_SERVICE_SURFACE=combined is restricted to local/test unless the temporary TR_ALLOW_DEPLOYED_COMBINED_SURFACE=true migration bridge is explicitly enabled ✅ (verified). TR_REMEDIATOR_MODE must be exactly off|observe|act.

Source priority (highest wins), from Settings.settings_customise_sources:

1. init kwargs (tests)
2. process environment (TR_*)
3. .env in the CWD
4. operator keys file ~/.quill_cloud_keys.private (_LocalKeyFileSource). Only for the 53 secret/integration fields listed in _LOCAL_KEY_FALLBACKS, looked up by the un-prefixed upper-case name (e.g. STRIPE_SECRET_KEY, GOOGLE_CLIENT_ID, SENTRY_DSN). Skipped entirely under pytest.
5. file secrets (pydantic default; unused)
6. code defaults in config.py

The operator keys file

• Dotenv-style, never committed. Parsed by secrets.LocalKeyFile (KEY=value, # comments, quotes stripped). Values are never logged.
• README documents /Users/jperla/claude/.quill_cloud_keys.private. That is Joseph's path. For you it is ~/.quill_cloud_keys.private (the code default). It does not exist on this Mac, and nothing needs it.
• Two consumers: 1. Settings fallback (above): integration secrets such as Stripe, OAuth, SES, PayPal, Adyen, Sentry, INTERNAL_GATEWAY_TOKEN and BOOTSTRAP_MANAGEMENT_KEY. 2. Provider client (providers.py::_secret): provider keys such as ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, CEREBRAS_API_KEY, DEEPSEEK_API_KEY and MISTRAL_API_KEY. It checks the keys file first and then the bare process env. These are not TR_-prefixed.
• Aliases (secrets.KEY_ALIASES): CLAUDE_API_KEY→Anthropic, CHATGPT_API_KEY→OpenAI, STRIPE_KEY→STRIPE_SECRET_KEY, ZHIPU_API_KEY/Z_AI_API_KEY→ZAI_API_KEY, TOGETHERAI_API_KEY→Together, DASHSCOPE_API_KEY→Alibaba, and Vertex project/region/token aliases.
• Vertex in production uses the service account and ADC, not a long-lived key in this file.
• ⚠️ Gotcha (code-verified): TR_LOCAL_KEYS_FILE changes the path the provider client reads, but _LocalKeyFileSource reads settings_cls.model_fields["local_keys_file"].default, which is always ~/.quill_cloud_keys.private. So the Settings fallback for Stripe, OAuth and the rest ignores TR_LOCAL_KEYS_FILE. .env.example sets it to Joseph's path. If you copy .env.example verbatim, provider keys are read from a non-existent file, while integration secrets still come from ~/.quill_cloud_keys.private.

Production: config-as-code

• Runtime env for Cloud Run is the ENV_VARS array in scripts/deploy/rollout.sh (~120 TR_* entries; joined with ^|^ and passed as --set-env-vars). Setting a Cloud Run env var by hand is a no-op. The next rollout overwrites it. To change prod config, edit rollout.sh in a PR.
• Notable prod values: TR_ENVIRONMENT=production, TR_SERVICE_SURFACE=combined with TR_ALLOW_DEPLOYED_COMBINED_SURFACE (temporary bridge until #712), TR_RATE_LIMIT_ENABLED=false (no trusted edge client identity yet), TR_ENABLE_LIVE_PROVIDERS=false, TR_REMEDIATOR_IN_PROCESS_ENABLED=false, TR_SIGNUP_TRIAL_CREDIT_MICRODOLLARS=300000, and TR_STORAGE_BACKEND=${STORAGE_BACKEND} (spanner-clickhouse per README).
• Secrets come from GCP Secret Manager via --update-secrets:
• Mandatory SECRET_ENVS: TR_SENTRY_DSN, TR_STRIPE_SECRET_KEY, TR_STRIPE_WEBHOOK_SECRET, TR_INTERNAL_GATEWAY_TOKEN, and the async-settle Ed25519 PEM mounted as a file at /secrets/async-settle/ticket.pem. A missing one fails the deploy.
• About 67 optional ones, added through add_secret_env_if_exists only when the secret exists in the inventory; otherwise they are explicitly --remove-secrets'd. These include provider keys (ANTHROPIC_API_KEY … ZERO_G_API_KEY), OAuth client ID/secret, Twilio/Telnyx/Veriff, PayPal/Routable/Adyen, AWS keys, AXIOM_API_TOKEN and the federation/operator tokens.
• Non-GCP deployments (AWS/Azure) have their own workflows (deploy-aws-control-plane.yml, deploy-azure-control-plane.yml) and use Workload Identity Federation (TR_GOOGLE_EXTERNAL_CREDENTIAL_CONFIG in scripts/entrypoint.sh, which refuses key material). See 04-infra-deploy.

flowchart TD
    D["Code defaults<br/>src/trusted_router/config.py::Settings<br/>(354 fields, local-safe)"]
    K["Operator keys file<br/>~/.quill_cloud_keys.private<br/>(un-prefixed names; 53 secret fields only;<br/>skipped under pytest)"]
    E[".env in CWD<br/>(gitignored; template: .env.example)"]
    P["Process env TR_*<br/>(shell, playwright webServer, CI)"]
    I["Init kwargs<br/>(tests: Settings(...))"]
    S(["Settings instance<br/>get_settings()"])
    D --> K --> E --> P --> I --> S

    subgraph PROD["Production (Cloud Run, GCP)"]
      R["scripts/deploy/rollout.sh<br/>ENV_VARS array → --set-env-vars<br/>(config-as-code; manual edits overwritten)"]
      SM["GCP Secret Manager<br/>SECRET_ENVS + add_secret_env_if_exists<br/>→ --update-secrets (env vars + PEM file mount)"]
      R --> P2["Container env TR_* + provider keys"]
      SM --> P2
    end
    P2 -. same precedence slot as .-> P

    PK["Provider API keys<br/>ANTHROPIC_API_KEY, OPENAI_API_KEY ...<br/>(keys file first, then bare env)"] --> PC(["ProviderClient<br/>live only if TR_ENABLE_LIVE_PROVIDERS=true"])
    K -. provider keys .-> PK

flowchart TD
    D["Code defaults<br/>src/trusted_router/config.py::Settings<br/>(354 fields, local-safe)"]
    K["Operator keys file<br/>~/.quill_cloud_keys.private<br/>(un-prefixed names; 53 secret fields only;<br/>skipped under pytest)"]
    E[".env in CWD<br/>(gitignored; template: .env.example)"]
    P["Process env TR_*<br/>(shell, playwright webServer, CI)"]
    I["Init kwargs<br/>(tests: Settings(...))"]
    S(["Settings instance<br/>get_settings()"])
    D --> K --> E --> P --> I --> S

    subgraph PROD["Production (Cloud Run, GCP)"]
      R["scripts/deploy/rollout.sh<br/>ENV_VARS array → --set-env-vars<br/>(config-as-code; manual edits overwritten)"]
      SM["GCP Secret Manager<br/>SECRET_ENVS + add_secret_env_if_exists<br/>→ --update-secrets (env vars + PEM file mount)"]
      R --> P2["Container env TR_* + provider keys"]
      SM --> P2
    end
    P2 -. same precedence slot as .-> P

    PK["Provider API keys<br/>ANTHROPIC_API_KEY, OPENAI_API_KEY ...<br/>(keys file first, then bare env)"] --> PC(["ProviderClient<br/>live only if TR_ENABLE_LIVE_PROVIDERS=true"])
    K -. provider keys .-> PK

Read the top chain as "lowest priority → highest priority". Each later source overrides the one before it.

7. Env var reference

7a. The ones you actually care about locally

.env.example (18 lines) contents, annotated: TR_ENVIRONMENT=local, TR_ENABLE_LIVE_PROVIDERS=false, TR_LOCAL_KEYS_FILE=/Users/jperla/... (⚠️ change it or drop it), TR_STORAGE_BACKEND=memory, and Spanner/Bigtable IDs (inert with memory; TR_BIGTABLE_* are not Settings fields any more, so extra="ignore" drops them). The rest are empty secrets plus the rate-limit numbers. ✅ Loading it verbatim gives local memory False … True combined and import trusted_router.main succeeds.

7b. Direct os.environ reads outside Settings

Most are in ops scripts, the synthetic monitor and deploy tooling, not in the request path: * Storage bootstrap scripts: TR_STORAGE_BACKEND, TR_GCP_PROJECT_ID, TR_SPANNER_INSTANCE_ID, TR_SPANNER_DATABASE_ID (20+ reads each in scripts/), TR_POSTGRES_DSN, TR_SPANNER_POOL_SIZE, TR_SCHEMA_*. * Synthetic monitor (synthetic/cli.py, image_generation.py, video_generation.py): TR_SYNTHETIC_*, TR_MONITOR_API_KEY, TR_EMBEDDINGS_*. * Deploy mutex/outcome: TR_DEPLOY_*. Smoke: TR_SMOKE_*, TR_API_BASE, TR_API_KEY. * serve.py: PORT, WEB_CONCURRENCY, UVICORN_*. entrypoint.sh: TR_GOOGLE_EXTERNAL_CREDENTIAL_CONFIG. * Provider keys via providers.py::_secret (keys file, then env), plus DATABRICKS_HOST/TOKEN, VERTEX_PROJECT_ID, etc. * CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE, GITHUB_TOKEN and GITHUB_STEP_SUMMARY in CI/ops scripts.

7c. Full Settings reference (all 354 fields, auto-generated)

Generated by introspecting Settings.model_fields and taking the first sentence of the comment directly above each field in config.py. Secret-looking fields never show values: they read None/"" or "(non-empty code default)". "Keys-file fallback = yes" means the field can come from ~/.quill_cloud_keys.private under its un-prefixed upper-case name. Grouping is by name prefix, so it is approximate. Required for local: none of them. Every field has a default, and the defaults target local + memory. Production requirements are enforced by the validators (production_is_fail_closed, operational_analytics_problems, …) and supplied by rollout.sh + Secret Manager.

Core runtime & surfaces (37)

Storage backends (Spanner/Postgres/ClickHouse) (25)

Security, auth & OAuth (49)

Rate limiting & admission (7)

Billing & payments (Stripe/PayPal/Adyen/Routable/x402/Veriff) (49)

Money path: settle/outbox/async settle/fastpath (50)

Trust / attestation (24)

Observability (Sentry/Axiom/synthetic/remediator) (45)

Notifications & email (SES/Twilio/Telnyx/ops chat) (33)

Legal entity metadata (14)

Other (21)

8. Troubleshooting (real issues hit during verification)

9. Safety reminders for local work

• Local dev needs zero cloud credentials. If something asks for gcloud auth, stop and check TR_STORAGE_BACKEND.
• Never point TR_SPANNER_* / TR_POSTGRES_DSN at production. AGENTS.md: unindexed tr_entities.body searches caused the 2026-09-06 CPU incident. Use python -m scripts.inspect_payment_owner for Stripe attribution and ClickHouse for analytics.
• Pushing to main auto-deploys the control plane when src/**, scripts/deploy/**, frontend/src/**, Dockerfile, pyproject.toml or uv.lock change.
• Money code (reserve/settle/refund) changes need a differential or conformance test, never review-by-eye.

10. Verification log (raw timings)