Community API Key — Zero-Setup Onboarding for Brainstorm CLI

2026-03-25

Community API Key

What We Built

A community-tier API key system that ships with the open-source Brainstorm CLI. First-time users can brainstorm chat immediately after install — no API key setup required. The shared key routes through BrainstormRouter with strict server-side limits.

Why It Matters

The #1 friction point for CLI adoption is API key setup. Community keys eliminate this entirely. Users get a working experience on day one, then upgrade when they need more. The key defaults to DeepSeek V3 — strong enough to impress, cheap enough to give away.

Key Design Decisions

• Reuse existing infrastructure — allowed_models, rate_limit_rpm, budget_limit_usd already existed on api_keys. Added only tier column + new middleware.
• New middleware, not modified existing — community-tier.ts has early exit for non-community keys (zero overhead for paying customers). Clean separation from rate-limit.ts and budget.ts.
• Redis counters with in-memory fallback — daily request/token counters and concurrent limiter in Redis. Falls back to per-process Maps when Redis unavailable (existing pattern).
• Transparency headers — X-BR-Requests-Remaining and X-BR-Tokens-Remaining on every response so the CLI can show "87 requests remaining today" in the status bar.

Limits

Limit	Value
Default model	DeepSeek V3
Allowed models	DeepSeek V3, DeepSeek R1, Haiku 4.5, GPT-4.1-mini, Gemini 2.5 Flash
Requests/day	100
Requests/minute	5
Daily budget	$2.00
Tokens/day	100,000
Input tokens/request	8,000
Output tokens/request	4,000
Concurrent	2
Strategy	Forced cost-first

Lockstep Traceability

Surface	Status	Files
API	Implemented	src/api/middleware/community-tier.ts, src/api/server.ts
DB	Implemented	src/db/migrate.ts (v44), src/db/schema/api-keys.ts
Auth	Implemented	src/api/middleware/auth.ts (tier on ResolvedApiKey)
Route	Implemented	src/api/routes/completions.ts (strategy/model/token overrides)
Tests	Implemented	src/api/middleware/community-tier.test.ts
SDK-TS	N/A	No new routes — middleware on existing completions endpoint
SDK-PY	N/A	No new routes
MCP	N/A	No new routes
CLI	N/A	Key embedded in Brainstorm CLI (separate repo)
Dashboard	N/A	Future: community usage analytics page