quantum-free-router - GitLite

KO | EN

gitlite — search

#rust #codex #terminal #windows #linux #golang #nodejs #llm #proxy #go

quantum-free-router

(★ 53)

Zero-cost LLM routing across free-tier model APIs with Bifrost, certification scripts, and agent-ready fallback chains

File Explorer

ZIP Download

- - ci.yml
- certification-models.txt
- hermes-fallback.example.yaml
- architecture.md
- configuration.md
- fallback-chain.md
- installation.md
- limits-and-reliability.md
- providers.md
- troubleshooting.md
- curl-test.sh
- hermes-agent.md
- openai-python.py
- certify-router.sh
- health-check.sh
- validate-config.py
.gitignore
CHANGELOG.md
CODE_OF_CONDUCT.md
config.template.json
CONTRIBUTING.md
install.sh
LICENSE
README.md
SECURITY.md
uninstall.sh

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`nano`

View Details ▼

Text editor. An enhanced `pico` clone.
See also: `pico`, `rnano`.

nano {{path/to/file1 path/to/file2 ...}}

Open specific files, moving to the next file after closing the previous one:

nano {{[-I|--ignorercfiles]}}

Start the editor without using configuration files:

nano +{{line}},{{column}} {{path/to/file}}

Open a file and position the cursor at a specific line and column:

🔍

`systemctl restart`

View Details ▼

Stop and then start one or more systemd units.
Can be used in place of `systemctl start` on a stopped unit, but `start` is safer so that a running unit isn't accidentally restarted.

systemctl restart {{unit}}

Restart a unit:

systemctl restart {{unit1 unit2 ...}}

Restart more than one unit:

systemctl restart {{unit}} --user

Restart a user unit:

# Project Badges

License: MIT Visit
Bifrost Visit
CI Visit
Free Tier Visit

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

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.

```text
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:

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

Add your free API keys:

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

Restart and verify:

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

Send a test request:

```bash
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](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](docs/providers.md)

## Curated Fallback Order

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

```text
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:

```python
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/openai-python.py)
- [examples/curl-test.sh](examples/curl-test.sh)
- [examples/hermes-agent.md](examples/hermes-agent.md)

## Repository Layout

```text
.
|-- 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

[![Star History Chart](https://api.star-history.com/svg?repos=spacepirate15/quantum-free-router&type=Date)](https://www.star-history.com/#spacepirate15/quantum-free-router&Date)

## Security

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

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

See [SECURITY.md](SECURITY.md).

## Credits

Built on [Bifrost](https://github.com/Portkey-AI/bifrost).

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

## License

MIT. See [LICENSE](LICENSE).