freellmpool › guide

How to run OpenCode on free LLM models

You can run the OpenCode coding agent on free LLM tiers — no API bill — by pointing it at a local proxy that speaks the OpenAI API. The open-source tool freellmpool is that proxy: it pools the free tiers of 24 providers (Groq, Cerebras, NVIDIA, Gemini, OpenRouter, Cloudflare, Morph, Vercel, Mistral, Cohere and more) behind one endpoint, with automatic failover. Several providers need no API key, so you can start for free in under a minute. It also ships an OpenCode plugin with a live dashboard, quality routing, and usage tools built in.

Release status: GitHub and PyPI both provide 0.11.4, including spread routing. Repository-local OpenCode plugin sources are included in 0.11.4; current main adds registry-readiness hardening, corrected defaults, and the operations APIs described below. Replace the released package to test that source explicitly:

python -m pip install --force-reinstall 'git+https://github.com/0xzr/freellmpool.git@main'

1. Choose a release or current-main install, then start the proxy

# Released 0.11.4:
python -m pip install freellmpool
# Or replace it with current main for the latest plugin support and operations APIs:
python -m pip install --force-reinstall 'git+https://github.com/0xzr/freellmpool.git@main'

freellmpool proxy            # serves http://localhost:8080

The proxy now routes OpenAI-style requests to a free provider and fails over when one is rate-limited.

2. Add freellmpool as an OpenCode provider

In your opencode.json (or ~/.config/opencode/opencode.jsonc), add a freellmpool provider and set it as your model. The routing aliases let you pick how each prompt is routed:

{
  "model": "freellmpool/auto",
  "provider": {
    "freellmpool": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "http://localhost:8080/v1" },
      "models": {
        "spread": {}, "auto": {}, "fast": {}, "quality": {}, "fair": {}
      }
    }
  }
}

Run freellmpool code opencode to print these steps any time.

3. Control routing quality from the model picker

Switch the model in OpenCode's picker to choose how freellmpool routes — no extra config:

freellmpool/spread — best starting point for long agent loops: use the least-used provider tier first, then prefer the faster/healthier target within that tier.
freellmpool/auto — the proxy's default routing.
freellmpool/quality — match each prompt's difficulty to the best and fastest capable free model (benchmark-scored, latency-aware).
freellmpool/fast — lowest-latency provider first.
freellmpool/fair — spread load across providers to preserve daily quota.

4. The embedded dashboard (optional, but fun)

freellmpool ships a native OpenCode TUI plugin that renders a live panel inside the editor — the active routing mode, estimated money saved, tokens served free, a provider "race," a latency sparkline, and which provider/model just answered. It updates as you code. Setup is in the integrations/opencode-tui folder; a companion server plugin adds freellmpool_status and freellmpool_models tools you can ask for in any session.

Registry publication status: pending. The planned packages are opencode-freellmpool and opencode-freellmpool-tui. Their tarballs are clean-install/load-tested, but neither package was published on npm as of 2026-07-19. Use the linked local-file setup until both registry versions are verified.

5. Operational checks (current main)

Before a long OpenCode run, automation can call public /livez for process liveness and /readyz for advisory local capacity. With proxy authentication, /v1/providers returns secret-free readiness details and /v1/models?ready=true returns only locally ready targets. These endpoints are current-main additions and readiness does not probe upstream providers.

Free-tier models are smaller than frontier models. They're great for scaffolding, refactors, tests, commit messages, and everyday edits — not a substitute for a frontier model on the hardest reasoning. Limits reset at UTC midnight; freellmpool/quality keeps effective quality high as caps fill.

6. (Optional) add free keys for more capacity

The keyless providers get you started; adding free API keys for Groq, Cerebras, Gemini and others unlocks more models and higher daily limits — see the accounts guide. freellmpool spreads load across whatever you have and tracks per-day usage so each tier drains evenly. Track your running total with freellmpool stats or embed a freellmpool badge in your README.

FAQ

Can I really use OpenCode for free?

Yes. freellmpool's proxy implements the OpenAI Chat Completions API and routes it to free-tier models, so OpenCode runs against them with no code changes. Quality is bounded by the free-tier models you have access to; freellmpool/quality routing picks the strongest fast-enough one per prompt.

Does freellmpool work with OpenCode's tool calls?

Yes — the proxy preserves tool/function calls across providers, and the bundled plugin adds extra tools (status, model list) plus the in-editor dashboard.

Is this against OpenCode's terms?

No — you're pointing OpenCode at a custom OpenAI-compatible provider, exactly the mechanism it supports for local and custom models. You're using the LLM providers' own free tiers; don't abuse them.

How do I see which free model OpenCode is using?

The embedded dashboard shows the last-served provider/model live; or ask the agent to run the freellmpool_status tool, or curl the proxy's /status endpoint.

Part of freellmpool (MIT, free, open source). Updated 2026-07-19.