FreeLLMAPI: run your coding agent for free

BEFORE YOU CLICK INSTALL

Your agent stops costing money. One npx command rewires Claude Code, Codex, Cline, Aider, Cursor or eleven more to http://localhost:3001/v1. Same tools, same workflow, same afternoon. The bill is the only thing that changes, and it goes to zero.

Free accounts, not a free trial. Google, Groq, Cerebras, Mistral, NVIDIA, Cloudflare and 28 more, each handing out a real monthly allowance. Sign-up is a browser tab. Nothing expires, no card, no countdown, and the router keeps you under every cap.

It gets dumber after dinner. Your best models carry the smallest daily allowances. Once they are spent the router walks down your chain to weaker ones, so the same question gets a worse answer at 9pm than at 9am. It resets at UTC midnight. The project's own warning.

The free build lags a month. The catalogue updates itself, but a free install runs the monthly snapshot, so a new model reaches you 30 days late and the free build sits about 303 models behind today. Nothing is crippled. Same-day updates cost $19 a year.

Your keys never leave the box. Provider keys sit encrypted in a SQLite file on your machine, decrypted in memory per request. The catalogue server never sees a prompt, a completion or a key. Your tools only ever hold one token.

Honest limitThis is for building and experimenting, and the project says so itself: no frontier model on tap all day, wildly variable speed, no SLA, and free tiers that change without warning. Ship something real and you swap in a paid key first.

Read the whole setup

Get to zero in ten minutes.

Drop your email and the rest opens: the one-command install, the three providers to add first, the chain order that matters, the command that points Claude Code at it, and the two ways it goes wrong.

One email. No follow-up unless I ship something that fits.

WHAT YOU NEED

Docker, for the one-liner and for Compose. That is the whole dependency list
OpenSSL, to generate the encryption key. Already on macOS and Linux
Node 20, only if you want the npx freellmapi setup-* generators
Free accounts. Start with Google, Groq and Cerebras. Sign-up is a browser tab each, and those three alone carry a working day
On Windows, the .exe from Releases is easier than Docker

INSTALL

One command, then five browser tabs

The installer creates ~/freellmapi, generates an encryption key, pulls the image and starts the container. Re-running it is safe: your .env and your key survive, and the container updates to :latest. Read the script first if you would rather not pipe to bash.

The install

terminalDocker required

$ curl -fsSL https://freellmapi.co/install.sh | bash → ~/freellmapi created, key generated, container up on 3001

Open http://localhost:3001, make the account, then add provider keys on the Keys page. Grab the unified freellmapi-... key from that page header. That single key is what every client gets from now on.

Prove itPoint any OpenAI client at http://localhost:3001/v1 with that key and ask for model auto. The reply carries an X-Routed-Via: <provider>/<model> header naming who actually served it. See a provider name there and the whole chain is working.

CONFIGURE

Four things, then leave it alone

Almost everything lives in the dashboard rather than a config file. .env holds four keys, and only one of them is required. The work that matters is the fallback chain: the order you drag models into is the order your money-free capacity gets spent.

~/freellmapi/.envthe whole file

ENCRYPTION_KEY=<64 hex chars, generated by the installer> PORT=3001 # optional, both have defaults REQUEST_ANALYTICS_RETENTION_DAYS=90 REQUEST_ANALYTICS_MAX_ROWS=100000

Setting	Default	Why I change it
Fallback chain order	the catalogue's own ranking	Put fast-and-adequate above slow-and-clever for agent work. An agent makes twenty calls where a chat makes one, so waiting on a queue costs you twenty times.
Routing strategy	balanced	Six are offered. `auto:fast` for tool loops and autocomplete, `auto:smart` when you are actually thinking. You can also ask for a strategy per request instead of switching globally.
Named profiles	none	Make a coding chain and a vision chain, then select one per request with `auto:<profile>`. Cheaper than reordering the whole chain every time you change task.
REQUEST_ANALYTICS_RETENTION_DAYS	90	Ninety days of every request on a laptop is more history than I need. Whichever of days or rows prunes first wins; `0` disables either limit.
ENCRYPTION_KEY	generated for you	Back it up the day you install. It encrypts every provider key in the database, and changing it does not re-encrypt them: that is a separate rotate command with the old key in hand.

Worth knowingOutside production the server will generate an ephemeral key at boot if one is missing, which means your stored provider keys stop decrypting on the next restart. Never run real keys that way. Take a copy of the database before rotating anything.

DAILY DRIVING

Point your tools at it, in this order

Add keys first and clients second, because a generator writes the model list it can see at that moment. The setup commands back up the existing config and merge rather than overwrite, and every one of them takes --dry-run.

terminalone command per tool

$ npx freellmapi setup-claude --url http://localhost:3001 --api-key freellmapi-... → existing config backed up with a timestamp, new models merged in $ npx freellmapi launch → starts Claude Code with the credentials in the child process only, never in a file

Keys first. Google, Groq and Cerebras, then add more when you see a provider running dry in the dashboard.
Then the agents. setup-claude, setup-codex, setup-aider and a dozen siblings. Claude Code reaches it over the Anthropic wire on /v1/messages.
Then the ordinary clients. Anything OpenAI-shaped: base URL http://localhost:3001/v1, model auto, and the unified key.
Watch the header. X-Routed-Via on every response tells you which provider served it. That is your debugging tool and your capacity gauge.

The launchers are the safer habit: launch for Claude Code and launch-codex for Codex inject the key into that process and nothing else, so no config file on your disk ever holds it.

WHEN IT DRIFTS

Two failures, both expected

Answers got noticeably worse this evening

Not a fault. Your top models hit their daily caps and the router walked down the chain. It resets at UTC midnight. If it bites every day, add two more providers rather than reordering what you have.

A provider suddenly 429s or rejects the key

A free tier changed without notice, which happens regularly. A free install waits up to 30 days for the catalogue fix. Disable that provider in the dashboard meanwhile, and check its console: some tiers now require a billing account on file.

Locked outA server install has an email and password, and there is no mail server to send a reset link. The one-time code is printed to the log: read it with docker compose logs -f freellmapi and enter it on the reset form within fifteen minutes.

THE SHAPE OF IT

Where everything lives

~/freellmapi/.envthe encryption key and the port server/data/freeapi.dbkeys, models, chain, analytics: the whole state ~/Library/Application Support/FreeLLMAPI/the desktop app's equivalent, on macOS logs/freeapi.logwhere the password reset code appears localhost:3001/v1/docsthe API surface, served by your own install

Copy the database and the .env together and the install has moved machines. Apart they are useless: the keys in that file only open with that key.

That is the whole setup

One command, three free accounts, one endpoint every tool points at. Tomorrow the agent can take the long way round a problem, and nothing about that costs you anything.

Open on GitHub →

↑ Unlocks the moment you submit the form above.

Point Claude Code at 7.4 billion free tokens.

Get to zero in ten minutes.

One command, then five browser tabs

Four things, then leave it alone

Point your tools at it, in this order

Two failures, both expected

Where everything lives

Raj Singh

Now spend it on something worth running.

Keep going