FreeRide
The OpenAI-compatible gateway for every free-tier provider.
One local endpoint that fans out across OpenRouter, Groq, NVIDIA NIM, HuggingFace, Cerebras, Cloudflare Workers AI, and your own Ollama. Hit a rate limit, fail over to the next provider. Your agent never knows.
Also wraps Claude Code, OpenAI Codex, and Google Gemini CLI — run all three without paying any of their vendors.
102M+ tokens served in 35 days. $0 spent.
Routed through community free-tier keys via this gateway.
Daily traffic: free-ride.xyz/models
curl -sSL https://api.free-ride.xyz/install.sh | sh
freeride run claude # or: freeride run codex / freeride run gemini
That's it. No accounts, no subscriptions, no FreeRide cloud. Local-first, BYO keys, your machine talks to providers directly.
Install
macOS / Linux:
curl -sSL https://api.free-ride.xyz/install.sh | sh
Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://api.free-ride.xyz/install.ps1 | iex"
The installer picks up uv, then pipx, then plain pip — whichever is on your system. Or install from source.
freeride init # interactive — collects keys, writes ~/.freeride/.env
freeride serve # gateway listens on localhost:11343
Get keys (any one is enough; more = better failover):
Run a coding agent — free
Three of the major coding CLIs ship a freeride run wrapper that works with no per-vendor key and no login. The gateway translates between each CLI's native wire protocol and our routing layer; you get the polished agent UX of each CLI, paid for entirely by free-tier providers.
Claude Code
freeride run claude
Inside the session, switch routing per request via /model:
| You type | What happens |
|---|
/model claude-opus-4-7 | Your Pro/Max subscription answers (passthrough to api.anthropic.com) — only if claude login has run |
/model freeride/free | Free providers answer; smart-router picks the model |
/model freeride/fast | Free; prefers Groq (low TTFT) |
/model freeride/quality | Free; prefers OpenRouter (widest catalog) |
/model freeride/coding | Free; pinned to a code-tuned model that reliably emits tool_use blocks |
Full guide: docs/agents/claude-code.md.
OpenAI Codex
freeride run codex
Whatever model the CLI picks (gpt-5-codex, gpt-5, etc.) is routed to a free upstream provider. The gateway translates the Responses-API wire format (with full SSE event protocol — response.output_item.added → output_text.delta → output_item.done → response.completed) so the CLI parses everything natively.
Note: codex uses bubblewrap for shell-tool sandboxing; on systems without it, file/shell tool calls fail (the model still works). Full guide: docs/agents/codex.md.
Google Gemini CLI
freeride run gemini
Any gemini-* model name routes to a free upstream provider. Translator handles Google's {contents, tools, generationConfig} shape both directions. Full guide: docs/agents/gemini.md.
Any other agent / SDK
# Aider / Continue.dev / hermes / your-own-tool — anything that speaks OpenAI:
freeride bind aider
freeride bind continue
# or just point it at the gateway directly:
OPENAI_API_BASE=http://localhost:11343/v1
OPENAI_API_KEY=any-string-here
How failover works
Per-request the chain is (provider, key), sorted by recent health:
- Try the head pair.
RATE_LIMIT or AUTH error → mark the key as cooling, try the next key on the same provider.MODEL_NOT_FOUND or QUOTA_EXHAUSTED → skip to the next provider.- 5xx / TIMEOUT → next pair.
- First successful response — stamp
X-FreeRide-Provider + X-FreeRide-Request-Id headers and ship.
