# FreeRide — OpenAI-compatible gateway for free-tier AI inference

> https://free-ride.xyz

## What is FreeRide?

FreeRide is a local OpenAI-compatible gateway that routes requests across free-tier inference providers (OpenRouter, Groq, NVIDIA NIM, Cloudflare Workers AI, HuggingFace, Cerebras, Ollama). Automatically fails over when rate limits or quotas are hit. No subscriptions, no vendor lock-in.

## When to Use This

Use FreeRide when building coding agents that need:
- Free-tier failover across multiple providers (Groq, OpenRouter, NVIDIA NIM, etc.)
- A single localhost:11343 endpoint that works with any OpenAI-compatible client
- Automatic rate-limit handling without manual key rotation
- BYO (bring your own) API keys with no hosted key service or shared pool
- Local-first routing where requests go directly from your machine to the provider

Typical use cases:
- Running Claude Code, OpenAI Codex, or Gemini CLI without vendor subscriptions
- Running Aider, Continue, Hermes, or other coding agents on free-tier models
- Maximizing free-tier coverage across providers without switching tools

## Quick Start

```bash
# Install freeride-gateway
curl -sSL https://api.free-ride.xyz/install.sh | sh

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

# Add your API keys (BYO)
freeride config

# Run your agent
freeride run claude    # For Claude Code
freeride run codex     # For OpenAI Codex
freeride bind aider    # For older agents

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

## API Reference

FreeRide implements the OpenAI Chat Completions API and Anthropic Messages API.

- **Base URL (local):** http://localhost:11343
- **Chat completions:** POST /v1/chat/completions
- **Models list:** GET /v1/models
- **Anthropic Messages:** POST /v1/messages
- **Health check:** GET /health

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

### Key Headers

- `X-FreeRide-Provider` — Which provider fulfilled the request (openrouter, groq, nvidia_nim, etc.)
- `X-RateLimit-Limit` — Provider-specific rate limit (when available)
- `X-RateLimit-Remaining` — Remaining requests in current window
- `X-RateLimit-Reset` — Unix timestamp when limit resets
- `Retry-After` — Seconds to wait before retrying (on 429/503)

### Error Responses

All errors return JSON with standard structure:

```json
{
  "error": {
    "message": "Human-readable error message",
    "type": "rate_limit_error",
    "code": "provider_exhausted"
  }
}
```

Error types:
- `invalid_request_error` — Bad request (400)
- `authentication_error` — Auth failed (401)
- `rate_limit_error` — All providers rate-limited (429)
- `quota_exhausted_error` — All quotas exhausted (503)
- `model_not_found_error` — Model not available (404)
- `server_error` — Internal error (500)

## Resources

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

## Architecture

FreeRide is a Python daemon that runs locally and implements the OpenAI/Anthropic APIs. 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), 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 with Retry-After header

The failover logic is transparent to the client. From the agent's perspective, it's a single endpoint that rarely rate-limits.

## License

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