Guide

Use OpenCode with a free LLM API

OpenCode is an open-source coding agent for the terminal and desktop. It accepts any OpenAI-compatible provider. This guide connects OpenCode to free models through FreeLLMAPI. One command writes the config and stores the key.

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 | bash

Open 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>
opencode

The command does three things:

  • It adds a freellmapi provider to ~/.config/opencode/opencode.json. The provider lists the models from your live catalog with their context limits.
  • It sets freellmapi/auto as 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.context is the maximum input tokens of the model. limit.output is the maximum tokens it can generate.
  • The top-level model uses the provider/model format. Without it, OpenCode keeps the model that it used before.
  • Every model id that you want to use must be in the models map. Add more ids from GET /v1/models.
Note on config versions: the OpenCode docs now describe a V2 config format with a 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.

Free models for OpenCode: tool calling and 128K+ context
ModelFree onContextFree limits (best offer)ToolsVision
GLM 5.3UnoRouter1M1 req/min
1 req/min per model
YesNo
GLM 5.3 FlashNVIDIA NIM, UnoRouter1M40 req/min
40 RPM
YesYes
Gemini 3.8 FlashGoogle AI Studio1MRecurring provider quotaYesYes
Qwen3.8 Flash NextAMD Radeon Cloud262KRecurring daily account allowanceYesNo
Qwen3.8 FlashElectronHub1M$0.25/week shared recurring creditYesYes
Gemini 3.7 FlashGoogle AI Studio1M10 req/min
20 req/day
250,000 tokens/min
~3M
YesYes
GPT-5.6 LunaElectronHub1M$0.25/week shared recurring creditYesYes
Dots3 Note PreviewKilo Gateway, OpenRouter512K20 req/min
50 req/day
50 req/day account-wide (1,000 after a $10 purchase)
YesYes
DeepSeek V4 FlashAMD Radeon Cloud, BazaarLink, ElectronHub1M10 req/min
50 req/day
Shared rate limit
YesNo
Qwen3.8 27BElectronHub, Groq, OVH AI Endpoints262K30 req/min
250 req/day
70,000 tokens/min
~6M
YesYes
Gemini 3.6 FlashGoogle AI Studio1M10 req/min
20 req/day
250,000 tokens/min
~3M
YesYes
Qwen 3.8 27BCloudflare Workers AI262KShared 10k neurons/dayYesYes

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_switch in 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

ProblemCauseFix
"Invalid API key" with a valid keyAn empty apiKey in the config overrides the key from /connectRemove apiKey from options, or run setup-opencode again
OpenCode does not use the new providerThe top-level model is not setSet "model": "freellmapi/auto"
Model not foundThe model id is not in the provider's models mapAdd the id to the map, or run setup-opencode again
{env:VAR} key is emptyOpenCode replaces an unset variable with an empty stringExport the variable in the same shell, or store the key with /connect
Tool calls failThe model has weak tool callingSelect a model from the table above
"All models rate-limited after N attempts"All keys are at their limitAdd keys from more providers, or wait for the cooldowns
Use every one of these through one key. FreeLLMAPI is an open-source, self-hosted router that puts all these free tiers behind a single OpenAI-compatible endpoint and fails over when one is rate-limited. Browse the catalog or go live.

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.

Sources

All guides · Browse all free models

Keep reading

All posts →
Guide

Best free LLM APIs 2026

Ten genuinely free LLM APIs worth using — ranked, with real limits.

Guide

Unlimited free AI tokens?

No free AI API is unlimited. The closest real thing: 10.1 billion free tokens a month behind one key.

Guide

How to get a free LLM API key

Get a working key in minutes — no credit card required.