# FreeLLMAPI

> An open-source, self-hosted router that aggregates free LLM tiers from 34 providers behind a single OpenAI-compatible endpoint with smart routing and automatic failover.

FreeLLMAPI is an open-source, self-hosted LLM router built by Tashfeen Ahmed under the MIT license. It aggregates the genuine free tiers of 34 AI providers — including Google AI Studio, Groq, Cerebras, NVIDIA, Mistral, OpenRouter, Cohere, Cloudflare Workers AI, Z.ai, HuggingFace, and more — behind a single OpenAI-compatible `/v1` endpoint. The project is actively maintained, with its latest release (v0.8.9) published in August 2026.

## What It Is

FreeLLMAPI is a personal-use LLM proxy and router that collapses dozens of provider free tiers into one unified API key. Instead of managing 34 different SDKs, rate limits, and failure modes, users point any OpenAI-compatible client at `http://localhost:3001/v1` and the router handles provider selection, failover, and quota tracking automatically. The router is MIT-licensed and fully self-hosted — provider keys stay encrypted in a local SQLite database and are never sent to the FreeLLMAPI service. A live model catalog, updated twice daily from a signed feed, tracks which models are free this week across the full provider fleet.

## How the Router Works

The routing engine uses six configurable strategies and live per-model speed, capability, and reliability scores to rank the fallback chain. On a 429 or 5xx response, the router cools down the failing key and retries the next model automatically. Key mechanics include:

- **Per-key rate tracking** — RPM/RPD/TPM/TPD counters per `(platform, model, key)` that learn providers' reported ceilings
- **Unified model profiles** — the same model across multiple providers collapses into one entry with strict in-group failover; named profiles (coding chain, vision chain) switch from the dashboard or per request
- **Sticky sessions** — conversations stay on one model for 30 minutes; an optional compact handoff note keeps context coherent on mid-chat switches
- **Fusion mode** — the virtual `fusion` model fans a prompt out to a panel of diverse free models in parallel, then a judge model synthesizes one answer from the drafts
- **Prompt compression** — opt-in pipeline deduplicates prompts, filters tool output, compacts repeated JSON, and trims stale context before routing

## API Surface and Client Compatibility

FreeLLMAPI exposes every major OpenAI-style surface: `/v1/chat/completions`, `/v1/responses` (for Codex CLI), `/v1/completions` (editor ghost-text autocomplete), `/v1/images/generations`, `/v1/videos/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/embeddings`, and `/v1/models` — all streaming and non-streaming. It also speaks the Anthropic Messages API wire format on `/v1/messages`, native Gemini on `/v1beta`, and opt-in Ollama emulation for clients like Zed and JetBrains AI.

Automated setup generators (`npx freellmapi setup-claude`, `setup-codex`, `setup-aider`, and eleven more) configure compatible coding agents in one command. Supported agents include Claude Code, Codex CLI, Cline, Roo Code, Continue, Aider, OpenCode, Goose, Qwen Code, Kilo Code, Cursor, Zed, and JetBrains AI.

## Deployment and Platform Support

The router runs anywhere Node.js 20+ runs — Windows, macOS, Linux, and ARM single-board computers including Raspberry Pi. Deployment options include:

- **One-liner Docker install** — `curl -fsSL https://freellmapi.co/install.sh | bash` sets up `~/freellmapi`, generates an encryption key, and starts the container
- **Desktop app** — a native menu-bar app for macOS (`.dmg`) and Windows (`.exe`) with a glass popover showing live request stats; no account or password required
- **Android (experimental)** — via Termux
- **Docker Compose, local dev, and production builds** — documented in `docs/install.md`

The admin dashboard is a React UI supporting 60 languages with automatic RTL layout for Arabic, Hebrew, Persian, and Urdu. It includes a playground, analytics (p50/p95/TTFT over 24h–90d windows), key management, and an MCP server at `/mcp` for agent introspection.

## Update: v0.8.9

The latest release, v0.8.9, was published on August 25, 2026. The GitHub repository was created in April 2026 and has seen rapid development, accumulating over 20,000 stars and nearly 3,000 forks. The catalog currently tracks 34 providers, 474 model families, and 635 free provider/model endpoints (584 chat, 41 embeddings, 7 transcription, 3 video), representing roughly 7.4 billion tokens per month of listed free-tier capacity according to the project's own catalog data. The project is explicitly scoped for personal experimentation and single-user use, not production workloads.

## Features
- OpenAI-compatible /v1 endpoint
- 34 free LLM providers aggregated
- 474+ model families / 635 free endpoints
- Smart routing with 6 strategies
- Automatic failover on 429/5xx
- Per-key RPM/RPD/TPM/TPD rate tracking
- Encrypted provider keys (AES-256-GCM in SQLite)
- Self-updating signed model catalog
- Anthropic Messages API surface (/v1/messages)
- Native Gemini /v1beta surface
- Ollama emulation for Zed and JetBrains
- Fusion multi-model synthesis mode
- Image, video, and audio generation routing
- Tool calling and structured outputs
- Sticky sessions with context handoff
- Prompt compression pipeline
- MCP server at /mcp for agent introspection
- React admin dashboard with analytics
- 60-language UI with RTL support
- Desktop app for macOS and Windows
- Docker one-liner install
- Automated setup generators for 12+ coding agents
- Response cache
- Encrypted DB backups
- Bulk key import/export

## Integrations
Google AI Studio, Groq, Cerebras, NVIDIA, Mistral, OpenRouter, Cohere, Cloudflare Workers AI, Z.ai (Zhipu), HuggingFace, ModelScope, Ollama, LM Studio, vLLM, llama.cpp, Claude Code, Codex CLI, Cline, Roo Code, Continue, Aider, OpenCode, Goose, Qwen Code, Kilo Code, Cursor, Zed, JetBrains AI, DeepSeek Harness, MiMo Code, Stripe, Docker

## Platforms
WINDOWS, MACOS, LINUX, ANDROID, WEB, API, JETBRAINS_PLUGIN, CLI

## Pricing
Open Source, Free tier available

## Version
v0.8.9

## Links
- Website: https://freellmapi.co
- Documentation: https://github.com/tashfeenahmed/freellmapi/blob/main/docs/README.md
- Repository: https://github.com/tashfeenahmed/freellmapi
- EveryDev.ai: https://www.everydev.ai/tools/freellmapi