Zkrouter

zk-router

Self-hosted LLM router. Sits between your OpenAI-compatible client and OpenRouter. On every request, it:

1. Classifies the request with a 14-dimension weighted scoring engine (free, < 1ms)
2. Detects mode overrides (/max, /complex, [simple], etc.)
3. Stamps the routing decision into a ZK compressed-state Merkle root
4. Forwards to the chosen model on OpenRouter
5. Tracks stats (requests, errors, savings, per-tier / per-model breakdown)

The killer feature: the Birth bot auto-provisions a sponsored OpenRouter key on first boot, so a fresh install needs zero configuration. No env vars. No signup. No credit card.

Install

git clone https://github.com/Solizardking/zk-router.git
cd zk-router
npm install
npm run build
npm start

The first npm start will:

1. Load or create your Solana wallet at ~/.zk-router/wallet.json (mode 0600)
2. Initialize the ZK journal at ~/.zk-router/zk/
3. Call the x402.wtf control plane to mint a sponsored OpenRouter key
4. Bind that key to your wallet and persist it at ~/.zk-router/birth/receipt.json
5. Start the proxy on http://127.0.0.1:18800

Subsequent boots reuse the cached receipt with no network call.

Quick Start

# 1. Start the router
npm start
# 🌅 birth: provisioned key sk-or-v1-ab… (fresh)
# zk-router proxy listening on http://127.0.0.1:18800

# 2. Point any OpenAI-compatible client at it
curl http://127.0.0.1:18800/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zkrouter/auto",
    "messages": [{"role": "user", "content": "What is 2+2?"}]
  }'

Routing Tiers

Rules handle 100% of requests in < 1ms with zero LLM cost.

Mode Overrides

Force a tier with a prefix — the LLM never sees it:

# Slash prefix
/simple What's 2+2?
/max Refactor this distributed system
/reasoning Prove sqrt(2) is irrational
/complex [simple]   # bracket prefix (alias names work too)

# Word prefix
deep mode: Why does this recursive CTE produce duplicates?
basic mode, What time is it in Tokyo?

# Aliases
simple, basic, cheap              → SIMPLE
medium, balanced                  → MEDIUM
complex, advanced                 → COMPLEX
max, reasoning, think, deep      → REASONING

See GET /v1/mode-aliases for the full list.

ZK-Stamped Routing

Every routing decision is appended to a Merkle tree in the ZK journal:

curl http://127.0.0.1:18800/v1/relay/zk | jq .

Each chat completion response includes:

X-ZK-Router-Model:       google/gemini-2.5-flash
X-ZK-Router-Tier:         SIMPLE
X-ZK-Router-Savings:      97%
X-ZK-Router-Reasoning:    score=-0.050 | short (8 tokens)
X-ZK-Router-Root:         0x…
X-ZK-Router-Index:        42

The root is the Merkle root after appending this call's receipt. Auditors can verify the chain by replaying the routing decisions against the local classifier.

Endpoints

Admin auth

All /v1/admin/* endpoints require Authorization: Bearer <CLAWDROUTER_ADMIN_SECRET>. If the env var is unset, all admin endpoints return 503 not_configured (defense in depth).

# Status
curl -H "Authorization: Bearer $CLAWDROUTER_ADMIN_SECRET" \
  http://localhost:18800/v1/admin/status

# Activate kill switch with 60s TTL
curl -X POST -H "Authorization: Bearer $CLAWDROUTER_ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"reason":"investigating abuse","ttlSec":60}' \
  http://localhost:18800/v1/admin/kill-switch

# Force the next 10 requests to use the REASONING tier
curl -X POST -H "Authorization: Bearer $CLAWDROUTER_ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"tier":"REASONING","requests":10}' \
  http://localhost:18800/v1/admin/set-tier-override

# Audit the last 100 routing decisions
curl -H "Authorization: Bearer $CLAWDROUTER_ADMIN_SECRET" \
  http://localhost:18800/v1/admin/audit

# Rotate the admin secret without a restart
export CLAWDROUTER_ADMIN_SECRET=new-secret
curl -X POST -H "Authorization: Bearer $CLAWDROUTER_ADMIN_SECRET" \
  http://localhost:18800/v1/admin/reload-config

Configuration

zkrouter.config.json is looked up in this order:

1. $ZKROUTER_CONFIG env var
2. ./zkrouter.config.json (cwd)
3. ~/.config/zk-router/config.json

If no file is found, built-in defaults apply. Edit to override the tier→model mapping:

{
  "port": 18800,
  "host": "127.0.0.1",
  "logLevel": "info",
  "openRouterBaseUrl": "https://openrouter.ai/api/v1",
  "tiers": {
    "SIMPLE":  { "primary": "google/gemini-2.5-flash",     "fallback": ["deepseek/deepseek-chat"] },
    "MEDIUM":  { "primary": "deepseek/deepseek-chat",      "fallback": ["anthropic/claude-haiku-4.5"] },
    "COMPLEX": { "primary": "anthropic/claude-sonnet-4.5", "fallback": ["openai/gpt-4o-mini"] },
    "REASONING": { "primary": "openai/o3",                "fallback": ["anthropic/claude-opus-4.5"] }
  }
}

Environment Variables

The 14-Dimension Classifier

The weighted score maps to a tier via configurable boundaries. Confidence is calibrated using a sigmoid function. > 2 reasoning markers forces the REASONING tier at high confidence.

Cost Impact

(Calculated against Claude Opus 4.5 baseline at $75/M output tokens.)

What makes this different

Credits

• Smart router — adapted from BlockRunAI/ClawRouter → FreeRouter (MIT)
• ZK primitives — ported from clawdrouter (MIT)
• Birth bot — ported from clawdrouter (MIT)
• OpenRouter integration — uses the OpenRouter Chat Completions API
• Sponsored key provisioning — powered by x402.wtf control plane

License

MIT