quantum-free-router

Professional free-tier LLM router for long-running coding and research agents.

quantum-free-router packages a Bifrost-based OpenAI-compatible router with a curated free-model catalog, install scripts, health checks, and certification tools. It is designed for agent workflows where one free model going down, timing out, or hitting quota should not stop the whole task.

OpenAI-compatible client
        |
        v
http://127.0.0.1:4000/v1
        |
        v
Bifrost provider router
        |
        +-- OpenCode Zen
        +-- KiloCode
        +-- NVIDIA NIM
        +-- Gemini
        +-- Mistral / Cerebras / Groq / SambaNova / Cohere

What Problem This Solves

Free LLM endpoints are useful, but they are operationally unstable when used one at a time:

• quotas reset at different times
• rate limits can appear mid-task
• provider catalogs change without warning
• some model IDs work directly but not through a router
• long-context or large models can timeout under load
• agent replies can fail if a single primary model is unavailable

This repository gives you a practical free-tier routing layer with:

• one local OpenAI-compatible base URL
• a documented provider/model catalog
• bounded timeout and retry settings
• model certification scripts
• systemd service setup
• clear docs for agent integrations

It does not hide provider limits. It helps you route around them cleanly.

Quick Start

One-command install on Linux or WSL2:

curl -fsSL https://raw.githubusercontent.com/spacepirate15/quantum-free-router/main/install.sh | bash

Add your free API keys:

nano ~/.quantum-free-router/config.json

Restart and verify:

sudo systemctl restart quantum-free-router
curl -fsS http://127.0.0.1:4000/health

Send a test request:

curl -s http://127.0.0.1:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer local-dev" \
  -d '{
    "model": "opencode/deepseek-v4-flash-free",
    "messages": [{"role": "user", "content": "Reply with exactly: ok"}],
    "temperature": 0,
    "max_tokens": 8
  }'

Detailed install docs: docs/installation.md

Supported Providers

Provider	Status	Notes
OpenCode Zen	Active	Strong current free default path.
KiloCode	Active	Nemotron and StepFun free routes.
NVIDIA NIM	Active and retry-later mix	Very useful catalog; some large models timeout under router bounds.
Mistral	Active when free key is available	Good low-latency fallback.
Cerebras	Active when free key is available	Fast GLM route in current tests.
Groq	Active when free key is available	Excellent late fallback latency.
SambaNova	Active when free key is available	DeepSeek route.
Cohere	Active when free key is available	Command-A fallback.
Gemini	Retry-later	Keep configured; free-tier daily quota can exhaust.
OpenRouter	Quarantine by default	Catalog may work while chat completion entitlement fails.

Provider details: docs/providers.md

Curated Fallback Order

The reference chain from the latest private certification run is documented in docs/fallback-chain.md. The best currently verified default for agent work is:

bifrost/opencode/deepseek-v4-flash-free

For clients that support their own fallback chain, use the ordered list in configs/certification-models.txt.

Client Examples

Python OpenAI SDK:

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:4000/v1",
    api_key="local-dev",
)

response = client.chat.completions.create(
    model="opencode/deepseek-v4-flash-free",
    messages=[{"role": "user", "content": "Reply with exactly: ok"}],
    temperature=0,
    max_tokens=8,
)

print(response.choices[0].message.content)

More examples:

• examples/openai-python.py
• examples/curl-test.sh
• examples/hermes-agent.md

Repository Layout

.
|-- install.sh
|-- uninstall.sh
|-- config.template.json
|-- configs/
|   |-- certification-models.txt
|   `-- hermes-fallback.example.yaml
|-- docs/
|   |-- architecture.md
|   |-- configuration.md
|   |-- fallback-chain.md
|   |-- installation.md
|   |-- limits-and-reliability.md
|   |-- providers.md
|   `-- troubleshooting.md
|-- examples/
|   |-- curl-test.sh
|   |-- hermes-agent.md
|   `-- openai-python.py
|-- scripts/
|   |-- certify-router.sh
|   |-- health-check.sh
|   `-- validate-config.py
|-- SECURITY.md
|-- CONTRIBUTING.md
|-- CODE_OF_CONDUCT.md
`-- CHANGELOG.md

Reliability Model

This project separates model outcomes into four buckets:

• active: passed router certification and suitable for fallback chains
• retry-later: free model exists but is quota-limited, slow, or transiently timing out
• configured-only: useful direct/provider candidate not yet certified through this router
• quarantine: wrong account entitlement, model retired, empty response, or incompatible endpoint shape

This is intentionally conservative. Free models should not be discarded casually, but they also should not sit in the active chain until they pass.

Stars

Security

Never commit real API keys. The repo ships only placeholders. Local user config lives at:

~/.quantum-free-router/config.json

See SECURITY.md.

Credits

Built on Bifrost.

The free-model catalog and provider notes were informed by public free-model research, including vava-nessa/free-coding-models, then validated against live router behavior before being added to this project.

License

MIT. See LICENSE.