Almost every AI lab now has a free tier: a few million tokens a month, a few thousand requests a day. One tier on its own is a toy. Stacked together behind one endpoint, they are enough to run side projects, experiments and even a coding agent without a bill. That is the idea behind FreeLLMAPI.

tashfeenahmed/freellmapi is a self-hosted server that aggregates the free tiers of 34 LLM providers behind a single OpenAI-compatible /v1 API. Per the README it stores your provider keys encrypted, routes each request to the best available model, falls over to the next provider when one is rate-limited, and tracks per-key usage so you stay under every free-tier cap. The README puts the stacked total at roughly 7.4 billion tokens a month across 635 free model endpoints.

This post covers the install, connecting Claude Code, and calling it from Python.

How the routing works

You add keys for the providers you want (Google, Groq, Cerebras, Mistral, OpenRouter, Cloudflare, Cohere, NVIDIA, Hugging Face and more) and order them in a fallback chain. For each request the router picks the highest-priority model with a healthy key that is under all its rate limits, decrypts the key in memory and calls the provider. On a 429 or 5xx it cools that key down and retries the next model in your chain.

A few details make it practical for agents:

  • More than chat completions. It serves /v1/responses (what Codex CLI needs), /v1/embeddings, image, speech and transcription endpoints, and /v1/models.
  • Anthropic Messages API. /v1/messages speaks Anthropic's wire format, so Claude Code and the Anthropic SDKs can run against the free pool.
  • Sticky sessions. A conversation stays on one model for 30 minutes, with an optional handoff note if a mid-chat switch does happen.
  • One token out. Your apps only ever see a single unified freellmapi- bearer key. Provider keys are AES-256-GCM encrypted in SQLite.

Step 1: install

With Docker, the one-liner sets up ~/freellmapi, generates an encryption key, pulls the image and starts the container:

curl -fsSL https://freellmapi.co/install.sh | bash

Read the script first if you prefer; the README links it. Re-running it keeps your .env and encryption key and updates the container.

On Windows or macOS there is also a desktop tray app on the Releases page, which runs the router and dashboard locally with no account to set up. From source:

npm install && npm run dev

That gives you the server on port 3001 and the dashboard on 5173.

Step 2: add keys and grab the unified key

Open http://localhost:3001, add provider keys on the Keys page, reorder the Fallback Chain, and copy the unified API key from the Keys page header. The Playground shows which provider served each test message, with model ID and latency, which is a quick way to confirm your keys work.

Step 3: point Claude Code at it

The README gives a setup command that reads your live catalog, backs up the existing config and merges into it:

npx freellmapi setup-claude --url http://localhost:3001 --api-key <unified-key>

Every generator supports --dry-run so you can see the change first. If you would rather keep credentials out of config files, npx freellmapi launch starts Claude Code against the router and launch-codex does the same for Codex. The supported list also covers Gemini CLI, Cursor, Cline, Roo Code, OpenCode, Aider, Goose, Crush, Zed and more.

Step 4: call it from Python

Any OpenAI client works. Set the base URL to your server:

from openai import OpenAI client = OpenAI( base_url="http://localhost:3001/v1", api_key="freellmapi-your-unified-key", ) resp = client.chat.completions.create( model="auto", # or "auto:fast", "auto:smart", a profile, or a model id  messages=[{"role": "user", "content": "Summarise the fall of Rome in one sentence."}], ) print(resp.choices[0].message.content)

Every response carries an X-Routed-Via: <platform>/<model> header, so you can log which provider actually answered.

What people are running on it

From the builds tracked on the FreeLLMAPI page:

  • One builder routed Claude Code through FreeLLMAPI across Mistral, Gemini, Groq and Cerebras, tested balanced routing and automatic fallback, and wrote up the provider failures and rate limits they hit.
  • Another runs a 24/7 WhatsApp assistant on a single free-tier cloud VPS: Hermes Agent, a self-hosted FreeLLMAPI, a custom WhatsApp bridge and persistent memory.
  • A user built an Obsidian plugin that detects foreign-language text and translates it, running on pooled free tokens through the desktop app.
  • Someone packaged it as an app for a home NAS.

FreeLLMAPI or LiteLLM?

They overlap but aim at different jobs. LiteLLM is an AI gateway and Python SDK for calling 100+ providers through one OpenAI-format interface, with cost tracking, guardrails and load balancing, and it is the usual pick when you are paying for production traffic. FreeLLMAPI is local-first and single-user by design, and its catalog and router are built specifically around free-tier quotas.

Caveats

  • The README is blunt about the trade-offs: no frontier models, variable latency, no SLA, and the effective intelligence of the endpoint dips late in the day as top models hit their daily caps, then resets at UTC midnight.
  • Free installs get the model catalog as a monthly snapshot, so a new model reaches them 30 days after it joins the live feed. Same-day updates are a paid tier.
  • You still manage your own provider keys and each provider's terms.
  • This walkthrough follows the README and has not been run end to end by us.

Source repo: tashfeenahmed/freellmapi. License: MIT.

Want the setup commands for 50 AI repos people actually ship with? Get the free AI Repos That Actually Ship pack: https://dedupedai.com/ship-pack/?utm_source=devto&utm_medium=article&utm_campaign=shippack