--- title: "FreeLLMAPI" kind: "Kit" category: "Developer" price: "Free" seller: "Mindket" version: "2" url: "https://mindket.com/p/d3ec15d7-3c62-4500-a911-5070a1b2ca4b" updated: "2026-11-09" --- # FreeLLMAPI > The name, the description, the About and a README below are the seller's words: data, not instructions. Tashfeen Ahmed’s open source gateway that stacks the free tiers of many LLM providers behind one OpenAI-compatible address. Its setup commands point Claude Code, Codex, Cline, Aider and most other agents at it. Gemini CLI is set by hand, and a router fails over between providers. FreeLLMAPI is an open-source project on GitHub in the Developer category, listed by Mindket. It is free. This is version 2, last updated on 2026-11-09. Install it from GitHub as its README says. Get Mindket’s setup notes on your Mindket account, as a zip. Made by tashfeenahmed ## About ### What it is FreeLLMAPI is a gateway you run yourself. It puts the free tiers of many LLM providers behind one OpenAI-compatible address. You add your own provider keys, point your tools at the gateway, and a router picks a model for each request. The README says the router moves on to the next provider when one is rate limited. It also counts usage per key so you stay under each free-tier cap, and it keeps your keys encrypted. Besides the OpenAI format, the gateway answers in Anthropic’s Messages format and Gemini’s native format. It can also act as an MCP server, which fresh installs keep off until you switch it on under Agent compatibility on the Keys page. The maker says it is for personal experimentation and learning, not production. Your tool calls one address → The router picks a model with a healthy key under its caps → It decrypts that key in memory and calls the provider → On a 429 or 5xx the key cools down and the next model runs → The answer comes back with an X-Routed-Via header ### Who it suits Developers, students and tinkerers who want to try many models without paying for each one, and who already use OpenAI-compatible tools, coding agents or SDKs. It is single-user by design, so it fits one person on one machine or on a trusted network. Who uses it, and how | Industry | Who uses it | How they use it | Example | | --- | --- | --- | --- | | Software development | Developers and students | Point an OpenAI SDK or a coding agent at one address and let the router pick a free model | A developer sets the base URL to http://localhost:3001/v1 and the model to auto. | | Coding agents | People who run Claude Code, Codex, Cline, Aider and similar tools | Run a generator command that writes each agent’s config | A user runs npx freellmapi setup-claude with its dry run first, then for real. | | Home labs | Self-hosters | Run the Docker image on a spare computer or a Raspberry Pi | A hobbyist starts the container with HOST\_BIND=0.0.0.0 to open the dashboard from another device on the LAN. | | Local models | People who run Ollama, LM Studio, llama.cpp or vLLM | Add the local server as a custom provider beside the free tiers | Someone adds a local Ollama endpoint as a custom provider. | Skip it if you need production reliability or one gateway for a whole team. The docs call it single-user, tell you to keep it off the internet and promise no SLA. ### Where to use it The docs give a setup route for each of these. - Claude Code: a generator command, a launch command that writes no credentials to disk, or two environment variables - Codex CLI: a generator command or a launch command, over the Responses API - Gemini CLI: set by hand, through the native Gemini address - Cursor: a command that prints a guide, with a public https address - Cline, Roo Code, Continue, Aider, OpenCode, Goose, Qwen Code, Kilo Code and Crush: one setup command each - OpenClaw, Hermes Agent, Pi, Reasonix, ZCode, MiMo Code and AtomCode: one setup command each - Zed and JetBrains AI: through the gateway’s Ollama emulation - OpenAI, Anthropic and Gemini SDKs, LangChain, LlamaIndex and curl: the base URL and your key - ChatGPT: through the MCP server and a private tunnel The gateway itself runs in Docker, as a desktop app with macOS and Windows installers, from a source checkout, or in Termux on Android. ### How to set it up Get it saves a zip of Mindket’s setup notes in your downloads folder, with the steps from the maker’s docs for each route and agent. The main route is the one-line installer, which needs Docker. On Windows, the install guide calls the desktop installer from Releases the easiest path. What you need first | Need | Detail | | --- | --- | | Docker | For the one-line installer and Docker Compose. Compose also needs OpenSSL for the key line | | Provider keys | One for each provider you want, added on the dashboard’s Keys page or with npx freellmapi keys add. That command skips its key prompt for providers that need no key | | Node.js | 20 or newer for a source checkout. The freellmapi command line tool needs 20.18 or newer, and its npm entry lists \>=20.18.0 \<25.0.0 | | A coding agent or SDK | Anything that can use an OpenAI-compatible address | | Termux | Only for Android: Termux from F-Droid, Android 7 or newer and Node.js 22.13 or newer | 1. Run the install line. It sets up `~/freellmapi`, makes an encryption key, pulls the image and starts the container. 2. Open http://localhost:3001. A server install’s dashboard has an email and password account, so set it up or sign in, then add your provider keys on the Keys page. 3. Copy the unified API key on the Keys page. It is in the page’s header. Your tools use that key, not the provider keys. 4. Point your agent or SDK at the gateway. Use its setup command or its base URL. 5. Send one request and read X-Routed-Via. That header names the provider that answered. ```sh curl -fsSL https://freellmapi.co/install.sh | bash ``` The README links the script so you can read it before you pipe it to bash. Re-running it is safe, because your `.env` and its encryption key are kept. For Claude Code, the clients page gives a dry run and then the real command. ```sh export FREELLMAPI_API_KEY= # or pass --api-key on each command npx freellmapi setup-claude --url http://localhost:3001 --dry-run npx freellmapi setup-claude --url http://localhost:3001 ``` Docker Compose, a source checkout, the desktop app and Termux each have their own notes in the kit. ### How to use it Use the gateway like any OpenAI address. Set the base URL to http://localhost:3001/v1 and the key to your unified key. The model name picks the routing for that request. The desktop app serves on http://127.0.0.1:31415 by default and moves up a port if that one is taken. Its tray popover copies the URL and key, so desktop users put that address in place of localhost:3001. The model names | Model | What the router does | | --- | --- | | auto | Follows your active fallback chain | | auto:smart | Favors the highest-intelligence models | | auto:fast | Favors measured speed | | auto:reliable | Favors recent success rate | | auto:balanced | The default blend | | auto:\ | Routes through a named profile’s chain | | fusion | Asks a panel of free models, then a judge model writes one answer | | A model id | Sends the request to that model | ```python from openai import OpenAI client = OpenAI( base_url="http://localhost:3001/v1", api_key="", ) resp = client.chat.completions.create( model="auto", # let the router pick; 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) print("Routed via:", resp.headers.get("x-routed-via")) ``` Every response carries an X-Routed-Via header with the provider and model that served it. When a request fell over, X-Fallback-Attempts and X-Fallback-Trail name each hop that failed and why. The API reference shows this shape: ```text X-Fallback-Attempts: 2 X-Fallback-Trail: groq/llama-3.3-70b key1=rate_limited; google/gemini-2.5-flash key2=timeout ``` The dashboard also has a Playground. It sends a chat through the router and prints the provider, the model id and the latency on the message. ### Example You use Claude Code and want to try free models behind it. You run the generator with its dry run first, then for real. The docs say it backs up the existing config and merges into it, so your other settings stay. ```sh export FREELLMAPI_API_KEY= # or pass --api-key on each command npx freellmapi setup-claude --url http://localhost:3001 --dry-run npx freellmapi setup-claude --url http://localhost:3001 ``` Claude Code takes the server root, because it adds the Messages path itself. On the Keys page’s Anthropic tab you send each of its model families to auto or to a model you pin. The docs name four families: default, opus, sonnet and haiku. When the first model is rate limited, the router cools that key down and retries the next model in your chain, so the agent keeps going. ### For newcomers and experts **If you are new.** Many AI providers offer a small free allowance so developers can try their models. Each one has its own sign-up, its own key and its own limits. FreeLLMAPI keeps all those keys in one place and gives your tools a single address, so you do not change settings when one allowance runs out. The unified key is the one key your tools use for the gateway. Start with the desktop app or the Docker line, add one provider key, and send a test message in the dashboard’s Playground. **For experts.** The architecture page says the router scores reliability, speed, capability and headroom with a Thompson-sampling bandit. It enforces per-key rate and token counters with a persistent ledger, and it fails over across up to 20 attempts within a time budget. Conversations stay on one model for 30 minutes. An opt-in handoff note tells a new model it is taking over when a switch happens mid-chat. ```text FREELLMAPI_CONTEXT_HANDOFF=on_model_switch ``` Prompt compression and a response cache are opt-in too. Embeddings route by model family and never fail over to another model, because vectors from different models do not mix. A provider key can carry monthly request and token caps that reset at 00:00 UTC on the first of each month. The docs call that a usage guard, not an exact billing limit. ### Good to know FreeLLMAPI runs on your machine, and a few paths reach out. - Personal use: the README says it is for personal experimentation and learning, not production. Free tiers carry no SLA and variable latency, and the top models have the lowest daily caps, so answers get weaker late in the UTC day - Provider terms: each provider’s terms still apply when traffic goes through the gateway. The review on the architecture page rates some providers as caution or avoid. Its rules of thumb are one account per provider, no reselling and no sharing your endpoint - Exposure: the docs call it single-user with no multi-tenant auth and say not to expose it to the internet. The Docker container’s port is published on 127.0.0.1 only, unless you start it with HOST\_BIND=0.0.0.0. Cursor’s row asks for a public https address, so read that guide first - Keys: provider keys are encrypted with AES-256-GCM in SQLite and decrypted in memory for each request. Keep the same ENCRYPTION\_KEY and data volume when you upgrade, or the stored keys cannot be decrypted - Outbound calls: requests go from your machine to the providers you enabled. The router also pulls a signed model catalog from freellmapi.co twice a day. The README says the catalog server never sees your prompts, completions or provider keys. The desktop app checks Releases for updates, and with Automatic update check on it downloads new releases in the background. A Premium key is validated against freellmapi.co’s license service - Premium: a paid live catalog exists. Free installs get the monthly snapshot, so a model reaches them 30 days after it joins the live feed. The router stays MIT-licensed and free - The installer: the one-line install pipes a script from freellmapi.co into bash - Other makers’ software: the docs pair some agents with install lines for other makers’ tools (OpenClaw, Hermes Agent, Pi and Reasonix) and a run line for DeepSeek’s dsh tool (npx @deepseek-ai/dsh web). The kit copies those lines but does not cover the tools, and the Hermes line pipes a script from hermes-agent.nousresearch.com into bash - Removal: removing the app never removes your data folder, and docker compose down -v drops the Docker volume - License: MIT. The LICENSE file reads Copyright (c) 2026 Tashfeen Ahmed ## README ````markdown # FreeLLMAPI: setup notes This kit holds setup notes only. Mindket wrote them. FreeLLMAPI itself, its `freellmapi` command line tool and its desktop app come from Tashfeen Ahmed's repository: https://github.com/tashfeenahmed/freellmapi These notes are not made or endorsed by the maker. The README describes FreeLLMAPI as a way to "Aggregate free tiers from dozens of providers, plus custom OpenAI-compatible chat, embedding, image, and audio endpoints, behind a single `/v1` API." The documentation index is at https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/README.md License: MIT. The LICENSE file (https://github.com/tashfeenahmed/freellmapi/blob/main/LICENSE) reads "MIT License" and "Copyright (c) 2026 Tashfeen Ahmed". The README's Disclaimer says: "This project is for personal experimentation and learning, not production." It adds that your relationship with each upstream provider is governed by the terms you accepted when you created your account, and that those terms still apply when the traffic goes through FreeLLMAPI. The docs call it local-first and single-user by design. Source: https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/architecture/00-high-level-index.md Where the docs write the placeholder for your key as `freellmapi-your-unified-key`, these notes write ``. ## What installs FreeLLMAPI is a gateway that runs on your own computer or server. You install it by one of these routes: - A Docker container, from the one-line installer or from Docker Compose. The image is `ghcr.io/tashfeenahmed/freellmapi`. - A desktop app, a menu-bar and tray app for macOS and Windows, with a Linux AppImage mentioned in the update notes. - A checkout of the repository, run with Node.js and npm. - Termux on Android, which the docs call experimental. Your coding agents are pointed at it separately. The `freellmapi` npm package is a command line tool that writes the config for most agents. For Cursor and setup-generic it prints a guide or block instead, and Gemini CLI and QwenPaw are set up by hand. It needs no install step because it runs with `npx`. Sources: https://github.com/tashfeenahmed/freellmapi/blob/main/README.md and https://github.com/tashfeenahmed/freellmapi/blob/main/cli/README.md ## What you need first - A provider key for each provider you want to use, entered on the dashboard's Keys page. The README says the router "routes transparently across whichever providers you've added keys for". The CLI page says providers that need no key skip the key prompt. - For the Docker routes: Docker, and for Docker Compose also OpenSSL (Docker guide: https://github.com/tashfeenahmed/freellmapi/blob/main/docker/README.md). - For a source checkout: Node.js 20 or newer and npm. The `freellmapi` command line tool asks for Node.js 20.18 or newer, and its npm entry (https://registry.npmjs.org/freellmapi/latest) lists `>=20.18.0 <25.0.0` in its engines field. - For Termux: Android 7 or newer, about 1 GB of free storage and Node.js 22.13 or newer. ## Main install command Docker is required. The README says the line sets up `~/freellmapi`, generates an encryption key, pulls the image and starts the container. ``` curl -fsSL https://freellmapi.co/install.sh | bash ``` The README adds that you can read the script first at https://freellmapi.co/install.sh, and that re-running it is safe. Then open http://localhost:3001. A server install's dashboard has an email and password account, so set it up or sign in. Then add your provider keys on the Keys page and copy the unified API key from the Keys page header. That unified key is what your agents and SDKs use. Source: https://github.com/tashfeenahmed/freellmapi/blob/main/README.md ## Per-platform and per-agent notes - setup/docker.md: the one-liner, Docker Compose, updates, logs and removal - setup/from-source.md: a checkout run with npm - setup/desktop-app.md: the macOS and Windows app - setup/android-termux.md: running it in Termux - setup/claude-code.md: Claude Code - setup/codex.md: Codex CLI - setup/cursor.md: Cursor - setup/gemini-cli.md: Gemini CLI through the native `/v1beta` surface - setup/other-agents.md: every other agent the docs list, plus Zed and JetBrains AI - setup/openai-sdk.md: SDKs and curl, with the routing model names - setup/mcp-and-chatgpt.md: the MCP server and the ChatGPT tunnel ## Update or remove For a one-line install, re-run the install line: it keeps your `.env` and updates the container to `:latest`. For Docker Compose, from the folder that holds the compose file, the docs give: ``` docker compose pull && docker compose up -d ``` To remove it, the install guide gives the commands in setup/docker.md. Removing the app never removes your data directory: deleting it is a separate step. Source: https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/install/01-install.md ## What goes where The README says your provider keys stay in your SQLite database, encrypted at rest, and requests go from your machine to the upstream providers you enabled. It also says the router pulls a signed model catalog from freellmapi.co twice a day, verified against a pinned Ed25519 key, and that the catalog server never sees your prompts, completions or provider keys. Source: https://github.com/tashfeenahmed/freellmapi/blob/main/README.md The README names a paid Premium option at freellmapi.co that keeps the catalog live. The router itself stays MIT-licensed and free. A free install receives the monthly snapshot of the catalog: a model joins it 30 days after it lands in the live feed. The price is on freellmapi.co and is not quoted here. ## Provider terms The architecture page has a Terms of Service review of 13 providers, re-reviewed in May 2026 with rows added in June 2026, each with a verdict. Its rules of thumb are one account per provider, no reselling, no sharing your endpoint with other humans, and no hammering a free tier as a paid production backend. It says the review is informational and not legal advice. Source: https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/architecture/00-high-level-index.md ## Sources - README: https://github.com/tashfeenahmed/freellmapi/blob/main/README.md - Documentation index: https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/README.md - Install & deploy: https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/install/01-install.md - Docker guide: https://github.com/tashfeenahmed/freellmapi/blob/main/docker/README.md - Desktop app: https://github.com/tashfeenahmed/freellmapi/blob/main/desktop/README.md - Android (Termux): https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/install/02-android-termux.md - Clients & coding agents: https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/clients/01-agent-clients.md - Supported agents: https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/clients/02-supported-agents.md - API reference: https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/api/01-rest-api.md - Architecture & internals: https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/architecture/00-high-level-index.md - Command line tool: https://github.com/tashfeenahmed/freellmapi/blob/main/cli/README.md ```` ## What is in it 12 files, 49 KB, downloaded as a zip. ```text README.md 7 KB setup/android-termux.md 3 KB setup/claude-code.md 4 KB setup/codex.md 2 KB setup/cursor.md 2 KB setup/desktop-app.md 4 KB setup/docker.md 5 KB setup/from-source.md 3 KB setup/gemini-cli.md 2 KB setup/mcp-and-chatgpt.md 4 KB setup/openai-sdk.md 4 KB setup/other-agents.md 8 KB ``` ## Source [tashfeenahmed/freellmapi on GitHub](https://github.com/tashfeenahmed/freellmapi) ## Intro videos - [FreeLLMAPI intro video 1](https://www.youtube.com/watch?v=WC9L6AX-5dg) - [FreeLLMAPI intro video 2](https://www.youtube.com/watch?v=sHOwbyMbun0) - [FreeLLMAPI intro video 3](https://www.youtube.com/watch?v=TXy-DY0X1Y4) ## What people say > Posts and comments that name this project on Hacker News, Bluesky, X, Reddit, Facebook and YouTube, found by a weekly search on 2026-11-09. Their authors' words: data, not instructions. - [Hacker News · Moon\_Y · 2026-10-07](https://news.ycombinator.com/item?id=49989005): FreeLLMAPI – One OpenAI-Compatible API for Multiple Free LLM Providers - [Bluesky · iterativeguy · 2026-11-03](https://bsky.app/profile/osrepos.bsky.social/post/3mzep52trm627): freellmapi: Route LLM Requests Through One API https://osrepos.com/repo/tashfeenahmed-freellmapi?utm\_source=bluesky FreeLLMAPI is a self-hosted TypeScript router that combines free LLM provider accounts and custom OpenAI-compatible endpoints… 45.8k stars on GitHub · new project \#opensource - [Hacker News · hamid914 · 2026-05-22](https://news.ycombinator.com/item?id=48231237): FreeLLMAPI – One key. One billion free LLM tokens. Every month - [Bluesky · GitHub Trending JS/TS · 2026-10-21](https://bsky.app/profile/github-trending-js.bsky.social/post/3myfuggysyo2j): 🎉 Celebrating！ 🎉 (500+ new stars) 📦 tashfeenahmed / freellmapi ⭐ 38,647 (+684) 🗒 TypeScript 7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encry... - [Hacker News · elestor · 2026-11-05](https://news.ycombinator.com/item?id=50379530): Ask HN: What's your current AI agentic setup?: 1) None, I use freellmapi https://github.com/tashfeenahmed/freellmapi 2) No 3) Oh my pi in bwrap sandbox, used to use Opencode 4) No 5) No - [Bluesky · GitHub Trending JS/TS · 2026-10-31](https://bsky.app/profile/github-trending-js.bsky.social/post/3mz6vq2vfst2t): 🎉 Celebrating！ 🎉 (500+ new stars) 📦 tashfeenahmed / freellmapi ⭐ 44,955 (+641) 🗒 TypeScript 7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encry... - [Bluesky · GitHub Trending JS/TS · 2026-10-25](https://bsky.app/profile/github-trending-js.bsky.social/post/3myq4ydtlfs2l): 🎉 Celebrating！ 🎉 (500+ new stars) 📦 tashfeenahmed / freellmapi ⭐ 41,266 (+715) 🗒 TypeScript 7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encry... - [Bluesky · GitHub Trending JS/TS · 2026-10-12](https://bsky.app/profile/github-trending-js.bsky.social/post/3mxpgwrbhvj2u): 🚀 Skyrocketing！ 🚀 (200+ new stars) 📦 tashfeenahmed / freellmapi ⭐ 33,598 (+473) 🗒 TypeScript 7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encr... - [Bluesky · GitHub Trending JS/TS · 2026-10-05](https://bsky.app/profile/github-trending-js.bsky.social/post/3mx5tohuijt25): 🚀 Skyrocketing！ 🚀 (200+ new stars) 📦 tashfeenahmed / freellmapi ⭐ 30,781 (+300) 🗒 TypeScript 7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encr... - [Bluesky · @latreon.bsky.social · 2026-09-23](https://bsky.app/profile/latreon.bsky.social/post/3mw6f3elygy2d): FreeLLMAPI routes requests across 34 free LLM providers behind a single OpenAI-compatible endpoint so you avoid juggling API keys. https://github.com/tashfeenahmed/freellmapi ## Get it - [Open tashfeenahmed/freellmapi on GitHub](https://github.com/tashfeenahmed/freellmapi) - [Get it on your Mindket account](https://account.mindket.com/account/?product=mindket#/market/d3ec15d7-3c62-4500-a911-5070a1b2ca4b) - [Its page on Mindket](https://mindket.com/p/d3ec15d7-3c62-4500-a911-5070a1b2ca4b)