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 catalogs 22 provider groups spanning recurring free tiers, keyless endpoints, finite trials, pin-only routes, and disabled candidates (178 enabled chat routes), and automatically fails over only across enabled routes you can access. It can start without provider credentials when an enabled keyless route is available. It also ships an OpenCode plugin with a live dashboard, quality routing, and usage tools built in.

Release status: Latest release: 0.13.0. GitHub and PyPI include spread routing and the operations APIs described below. Repository-local OpenCode plugin sources are included in 0.12.0 with registry-readiness hardening and corrected defaults.

1. Install the release, then start the proxy

python -m pip install freellmpool
freellmpool proxy            # serves http://localhost:8080

The proxy routes OpenAI-style requests to enabled targets you can access and fails over when one is rate-limited. A stream can fail over only before the downstream response is committed; after that, an upstream failure ends as a protocol error and never as a successful terminal event.

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/agent",
  "provider": {
    "freellmpool": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://localhost:8080/v1",
        "apiKey": "{env:FREELLMPOOL_PROXY_KEY}",
        "headerTimeout": 600000,
        "timeout": 600000,
        "chunkTimeout": 120000
      },
      "models": {
        "agent": {}, "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/agent — best starting point for long agent loops: stay in the strongest healthy benchmark tier, then spread quota and prefer faster targets within it.
freellmpool/spread — rotate across the whole pool when aggregate quota and breadth matter more than keeping every turn in the strongest 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-08-29. Use the linked local-file setup until both registry versions are verified.

5. Operational checks

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 released operations, and readiness does not probe upstream providers.

The proxy also serves a unified browser shell at /dashboard and /playground. Its public HTML contains no usage or inventory data. When proxy auth is configured, the page clears the token input, keeps the bearer only in a JavaScript closure, and sends it only in Authorization headers to the protected data and battle APIs. Reloading forgets it; it is never stored in a URL, cookie, Web Storage, rendered page, global, or log.

freellmpool capacity status          # cache-first; no external refresh
freellmpool capacity status --refresh
freellmpool doctor                   # strict, secret-safe config diagnostics

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. freellmpool's local per-day counters reset at UTC midnight; upstream providers use their own limit and reset windows. freellmpool/quality keeps effective quality high as local counters fill.

6. (Optional) add a local model runtime

freellmpool local discover
freellmpool local discover --name ollama
freellmpool local import --name ollama --yes
# Use the exact provider/model pin printed by import.
freellmpool local remove local_ollama --yes

The command probes only fixed LM Studio, Ollama, and llama.cpp literal-loopback endpoints, or one explicit canonical literal-loopback URL. It sends no credentials, follows no redirects, and does no DNS, LAN, or process scan. Confirmed imports are reversible and pin-only, so they do not silently join OpenCode's automatic routing aliases.

7. (Optional) add credentials for more capacity

If a keyless route is available it can get you started; applicable credentials for recurring free tiers such as Groq or Gemini can unlock more routes and capacity. Finite trials and priced or pin-only routes remain distinct — see the accounts guide. freellmpool spreads load across enabled routes you can access and tracks local per-day usage. 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-08-29.