krillswitch

OpenClaw's self-hosted feature flag service: a Cloudflare Worker (Hono + D1 + Drizzle) with a pure TypeScript evaluator and typed SDKs. Replaces LaunchDarkly for ClawHub.

Documentation: https://krillswitch.com

Local development

No Cloudflare account needed — everything runs in wrangler local mode.

corepack pnpm install
pnpm dev

pnpm dev creates .dev.vars from its example on first run, builds the admin dashboard, applies D1 migrations, seeds a clawhub project with a boolean souls flag, and starts the worker on http://localhost:8799 (the dashboard is served at that root; sign in with a dev persona — admin, editor, viewer, or nogrant. For real GitHub login, put OAuth app credentials in .dev.vars; see .dev.vars.example).

Evaluate the seeded flag:

curl -s -X POST http://localhost:8799/v1/eval \
  -H 'Authorization: Bearer ks_clawhub_development_local' \
  -H 'Content-Type: application/json' \
  -d '{"context":{"key":"some-user"}}'

{"flags":{"souls":{"value":true,"variationId":"var_souls_on","reason":{"kind":"default"}}}}

Toggle the flag in local D1 and the next response flips:

cd apps/api
pnpm exec wrangler d1 execute krillswitch --local \
  --command "UPDATE flag_environments SET enabled = 0 WHERE id = 'fe_souls_dev'"

Workspace

• apps/api — the Worker: POST /v1/eval, session-guarded /admin/* API, better-auth under /api/auth/*, D1 schema, seed fixture.
• apps/admin — the admin dashboard SPA (React + Vite), served from Worker assets.
• packages/core — @openclaw/krillswitch-core: flag/context types and the pure evaluateFlag function (no I/O).
• packages/react — typed React provider and hooks with local defaults, scoped persistence, ETags, and background refresh.
• packages/cli — human- and agent-friendly flag management with stable JSON.
• docs — Markdown source for the GitHub Pages documentation site.

Benchmarks

pnpm bench                                          # against the local stack
TARGET_URL=https://… TARGET_LABEL=workers-dev pnpm bench

Three scenarios run against POST /v1/eval and a dated JSON report lands in bench/results/ (UTC date + target label):

• sustained — autocannon load (default 25 connections, 15s) for round-trip p50/p95/p99, RPS, and error count. Exits nonzero above a 1% error rate so it can gate CI.
• server-timing split — a sampler alongside the load records each response's Server-Timing (cache hit/miss, eval/config/total processing). Workers isolate timers only advance on I/O, so 0ms hit-path processing means evaluation did no I/O.
• miss cadence — 10s of unloaded sampling; misses ≈ elapsed seconds proves at most one D1 read per second per environment.

Tool version is pinned (autocannon in root devDependencies) so results stay comparable. Keep load modest against deployed targets.

Commands

pnpm test       # core unit tests + worker integration tests (vitest)
pnpm typecheck  # tsc across workspaces (generates worker types first)
pnpm lint       # biome check
pnpm lint:fix   # biome check --write
pnpm docs:build # render and validate the documentation site

Releases

Krillswitch releases are versioned GitHub releases. The application version is declared in the root package.json; the workspace packages remain private and are not published to npm.

Security

Report vulnerabilities through GitHub private vulnerability reporting, not public issues.

License

MIT © OpenClaw Foundation. See LICENSE.