Step 1: Install FreeLLMAPI
FreeLLMAPI is an open-source gateway. It runs on your computer in Docker and pools the free tiers of 45 providers behind one key.
Install on macOS or Linux
curl -fsSL https://freellmapi.co/install.sh | bashOpen http://localhost:3001. Add at least two free provider keys on the Keys page. Google AI Studio and Groq each give a free key in a few minutes. Copy your unified key from the same page.
Step 2: Connect OpenCode with one command
One command
npx freellmapi setup-opencode --url http://localhost:3001 --api-key <unified-key> --dry-run
npx freellmapi setup-opencode --url http://localhost:3001 --api-key <unified-key>
opencodeThe command does three things:
- It adds a
freellmapiprovider to~/.config/opencode/opencode.json. The provider lists the models from your live catalog with their context limits. - It sets
freellmapi/autoas the default model. - It stores the key in OpenCode's credential file,
~/.local/share/opencode/auth.json. You do not need an environment variable, in the CLI or in the desktop app.
The command makes a backup before it writes. It merges the new provider, so your other providers stay. If XDG_CONFIG_HOME or XDG_DATA_HOME is set, the command uses those folders.
Before you start a long task, make sure that the gateway can serve a request now. This call lists only the models that have a usable key at this moment:
Check which models are ready
curl "http://localhost:3001/v1/models?execution_status=ready" \
-H "Authorization: Bearer <unified-key>"A model with the status exhausted has keys, but all of them are at a limit now. This status clears when the cooldowns end. Run npx freellmapi doctor to make sure that a client's requests reach the gateway. The dashboard request log shows each call from OpenCode. The X-Routed-Via response header names the provider and model that answered each request. If a request failed over, the X-Fallback-Trail header names each failed hop and the reason.
Manual setup: the opencode.json provider block
To set it up manually, add this block to ~/.config/opencode/opencode.json, or to opencode.json in your project. OpenCode uses @ai-sdk/openai-compatible for /v1/chat/completions endpoints.
opencode.json
{
"$schema": "https://opencode.ai/config.json",
"model": "freellmapi/auto",
"provider": {
"freellmapi": {
"npm": "@ai-sdk/openai-compatible",
"name": "FreeLLMAPI",
"options": {
"baseURL": "http://localhost:3001/v1"
},
"models": {
"auto": {
"name": "Auto",
"limit": { "context": 128000, "output": 8192 }
}
}
}
}
}Then add the key. Start OpenCode, run /connect, select the freellmapi provider and paste your unified key. The provider id in /connect must match the id in the config. Run /models to select a model.
limit.contextis the maximum input tokens of the model.limit.outputis the maximum tokens it can generate.- The top-level
modeluses theprovider/modelformat. Without it, OpenCode keeps the model that it used before. - Every model id that you want to use must be in the
modelsmap. Add more ids fromGET /v1/models.
providers key. The docs say that the V1 format above remains supported. The FreeLLMAPI setup command writes the V1 format.Choose models for OpenCode
OpenCode is an agent. It reads files, edits them and runs commands through tool calls. Each request carries a system prompt, tool definitions and file contents. Use models with tool calling and a large context window.
| Model | Free on | Context | Free limits (best offer) | Tools | Vision |
|---|---|---|---|---|---|
| GLM 5.3 | UnoRouter | 1M | 1 req/min 1 req/min per model | Yes | No |
| GLM 5.3 Flash | NVIDIA NIM, UnoRouter | 1M | 40 req/min 40 RPM | Yes | Yes |
| Gemini 3.8 Flash | Google AI Studio | 1M | Recurring provider quota | Yes | Yes |
| Qwen3.8 Flash Next | AMD Radeon Cloud | 262K | Recurring daily account allowance | Yes | No |
| Qwen3.8 Flash | ElectronHub | 1M | $0.25/week shared recurring credit | Yes | Yes |
| Gemini 3.7 Flash | Google AI Studio | 1M | 10 req/min 20 req/day 250,000 tokens/min ~3M | Yes | Yes |
| GPT-5.6 Luna | ElectronHub | 1M | $0.25/week shared recurring credit | Yes | Yes |
| Dots3 Note Preview | Kilo Gateway, OpenRouter | 512K | 20 req/min 50 req/day 50 req/day account-wide (1,000 after a $10 purchase) | Yes | Yes |
| DeepSeek V4 Flash | AMD Radeon Cloud, BazaarLink, ElectronHub | 1M | 10 req/min 50 req/day Shared rate limit | Yes | No |
| Qwen3.8 27B | ElectronHub, Groq, OVH AI Endpoints | 262K | 30 req/min 250 req/day 70,000 tokens/min ~6M | Yes | Yes |
| Gemini 3.6 Flash | Google AI Studio | 1M | 10 req/min 20 req/day 250,000 tokens/min ~3M | Yes | Yes |
| Qwen 3.8 27B | Cloudflare Workers AI | 262K | Shared 10k neurons/day | Yes | Yes |
Showing 12 of 109 matching free models. See all models.
Live data from the FreeLLMAPI catalog (version 2026.11.19, checked 19 November 2026). Free limits change often. The catalog is checked every day.
Use freellmapi/auto to let the router select a model for each request. Add auto:smart or auto:fast to the models map to steer requests by intelligence or speed. You can also add a named profile, for example auto:coding, after you make it on the dashboard.
Rate limits and long sessions
One agent task can send dozens of requests. A single free tier stops a long task fast. FreeLLMAPI counts each key's requests and tokens. When a provider sends a 429 error, the router sends the request to the next model in the chain, and the session continues.
- Add keys from four or more providers. More providers give more requests per day.
- Turn on context handoff with
FREELLMAPI_CONTEXT_HANDOFF=on_model_switchin the FreeLLMAPI.env. When the model changes, the next model gets a short note that it continues a task. - Sticky sessions keep a conversation on one model for 30 minutes. This keeps the agent consistent.
- Start a new session for each task. A smaller context uses fewer tokens per request.
Troubleshooting
| Problem | Cause | Fix |
|---|---|---|
| "Invalid API key" with a valid key | An empty apiKey in the config overrides the key from /connect | Remove apiKey from options, or run setup-opencode again |
| OpenCode does not use the new provider | The top-level model is not set | Set "model": "freellmapi/auto" |
| Model not found | The model id is not in the provider's models map | Add the id to the map, or run setup-opencode again |
{env:VAR} key is empty | OpenCode replaces an unset variable with an empty string | Export the variable in the same shell, or store the key with /connect |
| Tool calls fail | The model has weak tool calling | Select a model from the table above |
| "All models rate-limited after N attempts" | All keys are at their limit | Add keys from more providers, or wait for the cooldowns |
Frequently asked questions
Can I use OpenCode for free?
Yes. OpenCode is open source. Connect it to FreeLLMAPI as an OpenAI-compatible provider. The gateway sends each request to free provider tiers, so inference costs $0.
How do I add a custom OpenAI-compatible provider to OpenCode?
Add a provider with npm set to @ai-sdk/openai-compatible, options.baseURL and a models map to opencode.json. Then run /connect to store the key and /models to select a model.
Which free model is best for OpenCode?
Use a model with tool calling and at least 128K context. The table on this page shows the strongest free models that meet both rules today. Use freellmapi/auto to let the router select one.
Where does OpenCode store API keys?
Keys added with /connect go to ~/.local/share/opencode/auth.json. The FreeLLMAPI setup command writes the key there, so the CLI and the desktop app both find it.
Related guides
- Use Aider with a free LLM API
- Use Codex CLI with free models
- How to use Claude Code for free
- Best free coding model APIs
- Free OpenAI-compatible API base URLs
Sources
- OpenCode docs: providers (V1 config) (checked 20 November 2026)
- OpenCode docs: config (checked 20 November 2026)
- OpenCode docs: migrate from V1 (checked 20 November 2026)
- FreeLLMAPI CLI generators (checked 20 November 2026)
- FreeLLMAPI docs: context handoff (checked 20 November 2026)