# FreeRide — Local gateway for free-tier AI inference

https://free-ride.xyz

## Overview

FreeRide is a local OpenAI-compatible gateway for routing AI inference requests across free-tier providers with automatic failover. Designed for coding agents (Claude Code, OpenAI Codex, Gemini CLI, Aider, Continue) that need reliable free-tier access without subscriptions or vendor lock-in.

## When to Use This

**Use FreeRide when:**

- You run coding agents and want to maximize free-tier inference across Groq, OpenRouter, NVIDIA NIM, etc.
- You have multiple free-tier API keys and want seamless failover without manual key rotation
- You need a local-first solution where requests go directly from your machine to the provider (no proxy)
- You want a single localhost:11343 endpoint that works with any OpenAI-compatible client
- Your agent hits rate limits frequently and you want automatic failover to the next provider

**Specific jobs FreeRide is built for:**

- Running Claude Code, OpenAI Codex, or Gemini CLI without subscribing to Claude Pro, ChatGPT Plus, or Gemini Advanced
- Running Aider, Continue, Hermes, or other coding tools on free-tier models (Llama 3.1, Mixtral, DeepSeek-R1, etc.)
- Building multi-model workflows where different tasks go to different providers based on quota/availability
- Prototyping and development where free-tier limits are acceptable and cost is a hard constraint

**Don't use FreeRide if:**

- You need production SLAs, guaranteed uptime, or dedicated quota — use a paid service instead
- You can't tolerate occasional rate limits or quota exhaustion
- You need a hosted proxy or don't want to manage your own API keys

## Installation

```bash
# One-line install (macOS / Linux)
curl -sSL https://api.free-ride.xyz/install.sh | sh

# Or via pip/uv
pip install freeride-gateway
uv tool install freeride-gateway
```

## Quick Start

```bash
# 1. Add your API keys (BYO — bring your own)
freeride config

# 2. Run your agent
freeride run claude     # Wrap Claude Code
freeride run codex      # Wrap OpenAI Codex
freeride run gemini     # Wrap Gemini CLI

# For older agents (Aider, Continue, etc.)
freeride bind aider
freeride bind continue

# Or point any client to localhost:11343
export OPENAI_API_BASE=http://localhost:11343/v1
```

## API Reference

**Base URL (local):** http://localhost:11343

**Endpoints:**

- POST /v1/chat/completions — OpenAI chat completions (streaming, tools, vision)
- GET /v1/models — List models from all configured providers
- POST /v1/messages — Anthropic Messages API compatibility
- GET /health — Health check and provider count

**Key Response Headers:**

- `X-FreeRide-Provider` — Which provider fulfilled the request (openrouter, groq, nvidia_nim, etc.)
- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` — Rate limit info (when available)
- `Retry-After` — Seconds to wait before retrying (on 429/503)

**Full OpenAPI spec:** https://free-ride.xyz/openapi.json

## Failover Logic

When a request comes in:

1. Gateway selects first available provider based on model and quota state
2. If provider returns 429 (rate limit) or 403 (quota exhausted), tries next key/provider
3. If model not found, advances to next provider that supports it
4. On success, returns response with X-FreeRide-Provider header
5. If all providers fail, returns 503 Service Unavailable with Retry-After header

From the agent's perspective, it's a single endpoint that handles failover automatically.

## Supported Providers

- **OpenRouter** — Free-tier models (chat, streaming, tools, vision)
- **Groq** — Llama 3.x, Gemma 2, Mixtral, DeepSeek-R1 (daily token cap)
- **NVIDIA NIM** — Curated allowlist (credits per account)
- **Cloudflare Workers AI** — Cheap-per-neuron chat models (10K neurons/day)
- **HuggingFace** — Router catalog with fastest/cheapest pin ($0.10/mo Free, $2/mo PRO)
- **Cerebras** — Fastest Llama/Qwen inference (RPM/TPM caps)
- **Ollama (local)** — Your own machine, your own GPU (no quota)

## Resources

- **GitHub:** https://github.com/Shaivpidadi/FreeRideV3
- **PyPI:** https://pypi.org/project/freeride-gateway/
- **Developer Docs:** https://free-ride.xyz/developers
- **About:** https://free-ride.xyz/about
- **OpenAPI:** https://free-ride.xyz/openapi.json

## License

MIT — https://github.com/Shaivpidadi/FreeRideV3/blob/main/LICENSE

## Contact

Report issues, request features, or ask questions via GitHub:
https://github.com/Shaivpidadi/FreeRideV3/issues