Skip to content

Solizardking/clawd-bot / agent/skills/zkrouter

zkrouter

Verified

Self-hosted OpenAI-compatible LLM router β€” smart tier-based routing, ZK-stamped routing decisions, mode overrides, free OpenRouter at install via the Birth bot. Save 60-80% on inference costs by routing to the cheapest capable model across 12+ OpenRouter models.

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

TierExample queriesDefault modelCost (output / M)
SIMPLE"What is 2+2?", "Translate hello", "Yes or no"google/gemini-2.5-flash$2.50
MEDIUMSummaries, explanations, simple codedeepseek/deepseek-chat$1.10
COMPLEXMulti-step code, system design, agentic tasksanthropic/claude-sonnet-4.5$15.00
REASONINGProofs, math, multi-step logicopenai/o3$40.00

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

EndpointAuthDescription
POST /v1/chat/completions-OpenAI-compatible chat (model = zkrouter/auto or alias)
GET /v1/models-List available models + aliases
GET /v1/mode-aliases-List mode-override aliases
GET /v1/relay/zk-ZK primitives snapshot
GET /health-Health + uptime + stats
GET /stats-Full request statistics (per-tier, per-model, costs)
GET /config-Sanitized config + routing version
POST /reload-config-Hot-reload zkrouter.config.json
GET /v1/admin/statusadminOperator status: kill switch, tier override, audit queue
POST /v1/admin/kill-switchadminToggle the kill switch (refuse all /v1/chat)
GET /v1/admin/auditadminLast 100 routing decisions (incl. blocked)
POST /v1/admin/force-birthadminWipe receipt and re-provision a fresh OpenRouter key
POST /v1/admin/set-tier-overrideadminPin a tier for the next N requests
POST /v1/admin/reload-configadminRe-read zkrouter.config.json + reload env secret

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

VariableDefaultDescription
OPENROUTER_API_KEY-Skip the Birth bot; use this key directly.
CLAWDROUTER_ADMIN_SECRET-Bearer secret for /v1/admin/* (kill switch, force-birth, audit). Required for admin ops.
ZKROUTER_PORT18800Server port
ZKROUTER_HOST127.0.0.1Bind address
ZKROUTER_LOG_LEVELinfodebug / info / warn / error / silent
ZKROUTER_BIRTH_ENABLEDtrueMaster switch for the Birth bot
ZKROUTER_BIRTH_CONTROL_PLANE_URLhttps://x402.wtfControl plane base URL
ZKROUTER_BIRTH_VAULT_DIR~/.zk-router/birthReceipt directory
ZKROUTER_BIRTH_AUTO_TRIGGERtrueRun Birth on startup
ZKROUTER_BIRTH_TIMEOUT_MS8000HTTP timeout for the control plane
ZKROUTER_ZK_ENABLEDtrueMaster switch for ZK
ZKROUTER_ZK_STORAGE_DIR~/.zk-router/zkZK journal directory
ZKROUTER_ZK_TREE_DEPTH20Merkle tree depth (8 / 16 / 20 / 26)

The 14-Dimension Classifier

DimensionWeightDetection
Reasoning markers0.25"prove", "theorem", "step by step"
Technical terms0.18"algorithm", "kubernetes", "distributed"
Code presence0.12"function", "async", "import", "```"
Multi-step patterns0.12"first...then", "step 1"
Domain specificity0.12"quantum", "fpga", "zero-knowledge"
Simple indicators0.10"what is", "define", "translate"
Imperative verbs0.06"build", "create", "implement"
Token count0.04short (< 50) vs long (> 500)
Agentic task0.04"read file", "edit", "run", "test"
Creative markers0.05"story", "poem", "brainstorm"
Question complexity0.05Multiple question marks
Constraint count0.04"at most", "maximum", "limit"
Output format0.03"json", "yaml", "schema"
Reference complexity0.02"above", "the docs", "the api"
Negation complexity0.01"don't", "avoid", "without"

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

Tier% of TrafficOutput $/MSavings
SIMPLE40%$2.5097% cheaper
MEDIUM30%$1.1099% cheaper
COMPLEX20%$15.00best quality
REASONING10%$40.0047% cheaper
Weighted avg~$11.50/M~70% savings

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

What makes this different

FeatureOpenRouterLiteLLMzk-router
Open sourceβŒβœ…βœ…
Smart tier routingβŒβŒβœ…
Mode overridesβŒβŒβœ…
Free OpenRouter at installβŒβŒβœ… (Birth)
ZK-stamped routing decisionsβŒβŒβœ…
Zero-config startupβŒβŒβœ…
Multilingual classifierβœ…βŒβœ…
External config hot-reloadβŒβœ…βœ…
Agentic auto-detectionβŒβŒβœ…
Context-length-aware routing❌partialβœ…

Credits

License

MIT

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 192kUpdated Claude CodeCodexVerifiedInstall