freeride

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):

Provider	Free tier	Get a key
OpenRouter	rotating free models	openrouter.ai/keys
Groq	daily token cap	console.groq.com/keys
NVIDIA NIM	credits per account	build.nvidia.com
HuggingFace	$0.10/mo Free, $2/mo PRO	huggingface.co/settings/tokens
Cerebras	RPM / TPM caps	cloud.cerebras.ai
Cloudflare Workers AI	10K neurons/day	dash.cloudflare.com
Ollama (local)	no quota	install from ollama.com

---

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:

1. Try the head pair.
2. RATE_LIMIT or AUTH error → mark the key as cooling, try the next key on the same provider.
3. MODEL_NOT_FOUND or QUOTA_EXHAUSTED → skip to the next provider.
4. 5xx / TIMEOUT → next pair.
5. First successful response — stamp X-FreeRide-Provider + X-FreeRide-Request-Id headers and ship.