---

What FreeLLMAPI does

FreeLLMAPI is an open-source gateway (MIT license) that runs on your own machine. It speaks two dialects: the OpenAI API and the Anthropic Messages API. That is why it connects to almost any tool you already use, Claude Code included.

Here is what happens behind it: you store free API keys from the providers, for example Google, Groq or Mistral. For every request, a router picks the best available model. If a provider's quota runs out (HTTP 429) or the server errors, it tries the next model.

It counts usage per key so you stay under the limits. Your keys sit encrypted (AES-256-GCM) in a local SQLite database. Your apps only ever see a single key with the prefix freellmapi-.

The numbers from the README, as of October 29, 2026: 34 providers, 635 free model endpoints (584 of them for chat) and about 7.4 billion tokens per month of listed free capacity in total. That is the sum of the providers' limits according to the catalog.

How much of it reaches you depends on the keys you add. The repo now has over 40,000 stars on GitHub.

What you need

• Docker for the one-line install. Alternatively the desktop app for macOS and Windows.
• Node.js 20.18 or newer, only for the Claude Code setup command.
• Two or three free API keys from AI providers. Google (AI Studio), Groq and Mistral are enough to start. You create them with the providers themselves.

Step 1: Start the gateway

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

The script creates ~/freellmapi, generates an encryption key, pulls the Docker image and starts the container. You can read the script first: freellmapi.co/install.sh. Running it again is safe, your .env and the key stay in place and only the container updates.

Then open http://localhost:3001. Server installs (Docker, one-line script) are protected by an account with email and password. The desktop app signs itself in.

Two alternatives if you do not like piping a script into bash:

• Docker Compose: clone the repo, generate an ENCRYPTION_KEY with openssl rand -hex 32, write it into a .env (together with PORT=3001) and run docker compose up -d.
• Desktop app: the .dmg (macOS) or .exe (Windows) from the GitHub Releases. The only credential is the unified key in the tray popover.

Step 2: Add your free keys

1. Open the Keys page in the dashboard.
2. Pick a provider and enter your free key. A dot next to each key shows its status and when it was last checked.
3. Under Fallback Chain, sort the order in which the router tries models. The ones you want first go on top.
4. Copy your unified key from the header of the Keys page. It starts with freellmapi- and is the only key your tools ever see.

Start with three providers. More keys mean more free quota and more fallbacks, but also more terms of service you have accepted (more on that below).

Step 3: Test it

curl -i http://localhost:3001/v1/chat/completions \
  -H "Authorization: Bearer freellmapi-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "Say hello in one sentence."}]}'

"model": "auto" leaves the choice to the router. The response headers carry X-Routed-Via: provider/model, so you can see who actually answered. If the router had to fall back, X-Fallback-Attempts appears too.

Step 4: Point Claude Code at it

Claude Code expects the server's root URL, without /v1, because it appends the Anthropic API path itself. There are three ways.

Option A: the setup command. It reads the models from your live catalog, backs up your configuration and merges the change into the existing one:

npx freellmapi setup-claude --url http://localhost:3001 --api-key freellmapi-your-key --dry-run
npx freellmapi setup-claude --url http://localhost:3001 --api-key freellmapi-your-key

The first call only shows you the diff, the second writes it.

Option B: launch. Starts Claude Code with the credentials for that one run only, nothing lands in a config file:

export FREELLMAPI_API_KEY=freellmapi-your-key
npx freellmapi launch

For bridging an empty limit, this is my way: you start the free variant on purpose and your normal setup stays as it is.

Option C: by hand.

export ANTHROPIC_BASE_URL=http://localhost:3001
export ANTHROPIC_AUTH_TOKEN=freellmapi-your-key
claude

Use ANTHROPIC_AUTH_TOKEN, not ANTHROPIC_API_KEY. Claude Code treats a set ANTHROPIC_API_KEY as a conflicting login and refuses to start.

Which free models sit behind the Claude names is controlled in the dashboard under Keys, tab Anthropic: each family (default, opus, sonnet, haiku) runs on auto or on a model you pin.

Use case 1: bridge an empty Claude limit

This is the reason I am showing the tool at all. Your limit is empty, the reset is hours away and you want to keep moving. You start Claude Code through FreeLLMAPI (option B) and hand it tasks small enough for a weaker model:

• Write boilerplate and config files
• Add tests for existing code
• Rename variables, restructure files, write comments and docs

My rule of thumb: for grunt work this is enough, for demanding coding you are better off waiting until your limit is back. Architecture decisions do not belong on a free model that is already half used up by the afternoon (more under the limits below). If you want different behavior for code than for chat, set the header X-FreeLLM-Task-Type: code. It shifts the router's weighting slightly toward intelligence over speed.

Use case 2: batch processing with a script

The same gateway serves any OpenAI-compatible script. You only swap the base URL. An example: sorting customer messages by sentiment.

from openai import OpenAI

client = OpenAI(base_url="http://localhost:3001/v1", api_key="freellmapi-your-key")

texts = ["Shipping takes forever.", "Great support, thanks!", "How do I cancel?"]

for text in texts:
    reply = client.chat.completions.create(
        model="auto:fast",
        messages=[
            {"role": "system", "content": "Answer with exactly one word: positive, negative or neutral."},
            {"role": "user", "content": text},
        ],
    )
    print(text, "->", reply.choices[0].message.content.strip())

auto:fast ranks models by measured speed. There are more strategies: auto:smart (highest intelligence), auto:reliable (recent success rate) and auto:balanced (the default mix). With hundreds of texts, a single provider's quota will run out at some point, the router falls back, and your script does not notice. The gateway also covers embeddings (/v1/embeddings), transcription and image generation, as far as a provider on your list offers them for free.

Use case 3: fusion as a second opinion

With the virtual model fusion, the router sends your question in parallel to several different free models. A judge model builds one answer from the drafts. That helps where a single answer would be too random: checking a decision, probing a plan for gaps, or reading code for weaknesses.

curl http://localhost:3001/v1/chat/completions \
  -H "Authorization: Bearer freellmapi-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "fusion", "messages": [{"role": "user", "content": "Check this plan for weaknesses: ..."}]}'

Which models sit on the panel and which one judges, you set in the dashboard under Fusion or per request through the fusion field. Every sub-call goes through normal routing and uses quota. A fusion request therefore costs you a multiple of a normal one.

Common mistakes

• Claude Code does not start and reports a conflict. You set ANTHROPIC_API_KEY. Use ANTHROPIC_AUTH_TOKEN.
• The connection fails. Check the base URL. Claude Code gets http://localhost:3001, OpenAI-compatible tools get http://localhost:3001/v1.
• The dashboard does not load from another device. The container only listens on 127.0.0.1. Start it with HOST_BIND=0.0.0.0, but only on your home network.
• Providers are unreachable from Docker but fine from your machine. A proxy on 127.0.0.1 does not apply inside the container. Set PROXY_URL=socks5h://host.docker.internal:7890 (adjust the port) and let the proxy accept connections from outside loopback.
• Forgot your password (server install). Click "Forgot password?" on the login page. The code is printed in the server log (docker compose logs -f freellmapi) and is valid for 15 minutes.
• A provider suddenly returns 429 or auth errors. Providers change free tiers without warning. The catalog compensates automatically, more on that in a moment.

Limits you should know

The limits are stated in the repo itself, I pass them on unvarnished:

• No sustained access to the strong models. The catalog does list frontier-class models. Those are exactly the ones with the smallest daily allowances, the longest queues and the highest risk of being pulled on short notice.
• Quality drops over the course of the day. Your top models hit their daily caps first. After that, the router falls back to smaller models in your chain. It resets at midnight UTC.
• Latency varies a lot. Cerebras and Groq are very fast, others are not. You get whatever is free right now.
• There is no availability guarantee. If you need reliable answers, use a paid provider with a contract.
• It is a project for experimenting, not for production. That is what the repo's disclaimer says. If you build something real on top, swap in a paid API before you go live.
• Each provider's terms still apply, even when traffic runs through the gateway. The repo reviewed them in May 2026: it advises against Cohere and urges caution with Google, NVIDIA and Z.ai. Check the terms of the providers whose keys you add.
• Run it locally only. There is no multi-user login.

On the catalog: free installs pull it from a monthly snapshot. A new model arrives there 30 days later than on the paid tier (19 US dollars a year, according to the README). Everything works without it. According to the README, prompts, responses and provider keys stay with you.

Next steps

• Add providers one at a time and watch in the dashboard which models the router picks first.
• Create a named fallback chain called coding in the dashboard and address it with auto:coding.
• Read the docs in the repo for more agents such as Codex CLI, Cline, Aider or Cursor. You set up most of them with npx freellmapi setup-<agent>.