@clervo/beacon

@clervo/beacon

Zero-config LLM router. Drop-in OpenAI base URL replacement that routes to the cheapest working model automatically.

npx @clervo/beacon

Then point any OpenAI SDK at it:

from openai import OpenAI
client = OpenAI(base_url="http://localhost:4000/v1", api_key="unused")
response = client.chat.completions.create(
    model="gpt-4o",  # Routes to best free model
    messages=[{"role": "user", "content": "Hello"}]
)

Why?

• Free AI — 13 models, no API key, no payment, no signup
• 170ms latency — Groq-powered inference
• OpenAI-compatible — works with any SDK expecting OpenAI format
• Auto-routing — gpt-4o routes to the best free model; clervo/code routes to Claude Sonnet 5
• Budget caps — --budget 5 limits USDC spend to $5

Install

npm install -g @clervo/beacon
# or run directly
npx @clervo/beacon

Usage

# Start with defaults (port 4000, free models only)
npx @clervo/beacon

# Custom port
npx @clervo/beacon --port 8080

# Allow paid models with $5 budget
npx @clervo/beacon --budget 5

# Verbose mode (see routing decisions)
npx @clervo/beacon --verbose

As OpenAI base URL

export OPENAI_BASE_URL=http://localhost:4000/v1
export OPENAI_API_KEY=unused

Node.js

import OpenAI from 'openai';
const client = new OpenAI({ baseURL: 'http://localhost:4000/v1', apiKey: 'unused' });
const res = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello' }]
});

Python

from openai import OpenAI
client = OpenAI(base_url="http://localhost:4000/v1", api_key="unused")

curl

curl http://localhost:4000/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

Model Routing

You request	Beacon routes to	Speed	Cost
gpt-4o-mini	clervo/fast (Llama 3.1 8B)	170ms	Free
gpt-4o	clervo/smart (Llama 3.3 70B)	475ms	Free
gpt-4	clervo/smart (Llama 3.3 70B)	475ms	Free
claude-3-haiku	clervo/fast (Llama 3.1 8B)	170ms	Free
claude-3-sonnet	clervo/smart (Llama 3.3 70B)	475ms	Free
clervo/fast	groq/llama-3.1-8b-instant	170ms	Free
clervo/smart	groq/llama-3.3-70b	475ms	Free
clervo/deep	nvidia/nemotron-ultra-550b	~1s	Free
clervo/code	tongkhokr/claude-sonnet-5	2.6s	$0.015

Any provider/model format passes through directly to Clervo.

Available Models (via Clervo)

Free (13 models):

• clervo/fast, clervo/smart, clervo/deep
• groq/llama-3.1-8b-instant, groq/llama-3.3-70b, groq/qwen3.6-27b
• groq/gpt-oss-120b, groq/gpt-oss-20b
• sambanova/llama-3.3-70b
• nvidia/nemotron-ultra-550b, nvidia/nemotron-super-120b, nvidia/nemotron-nano-30b
• nvidia/deepseek-v4-flash

Paid ($0.002–$0.025 per call, USDC on Base):

• clervo/code, quickai/gpt-5.4-mini, quickai/gpt-5.4, quickai/gpt-5.5
• tongkhokr/claude-haiku-4.5, tongkhokr/claude-sonnet-5, tongkhokr/claude-opus-5

How it works

• You send a request to Beacon (local proxy)
• Beacon resolves the model to the cheapest working option
• Request is forwarded to Clervo's gateway (api.clervo.dev)
• Response streams back to you

No API keys needed. Free models require no payment. Paid models use x402 (USDC on Base mainnet, auto-settled).

Comparison

Feature	@clervo/beacon	LiteLLM	OpenRouter
Free models	13	0	0
Setup time	0 (npx)	Config file	Account + key
Latency overhead	~5ms	~10ms	~50ms
Payment	x402 (USDC)	API key	Credit card
Budget limits	Built-in	No	Soft limits

License

MIT