OpenCode + Ollama: Run the #1 Open-Source Coding Agent on Local Models

Short answer: install OpenCode with curl -fsSL https://opencode.ai/install | bash, then run ollama launch opencode — Ollama wires itself up automatically. Best local model: qwen3-coder:30b (19GB download, 256K context) on 24GB+ VRAM, or gpt-oss:20b (14GB, 128K) on a 16GB card. One thing will bite you: OpenCode wants a 64K+ context window and Ollama defaults to 4,096 tokens — fix it with OLLAMA_CONTEXT_LENGTH=65536 before you blame the model.

That is the whole setup. The rest of this guide is the detail that keeps it from falling over: the manual opencode.json config for when auto-setup is not enough, why the context window silently breaks tool calling, which model sizes are genuinely usable for agentic edits on real hardware, and an honest section on where a local model still loses to the frontier. Everything below was verified against the official OpenCode and Ollama docs in early August 2026, on OpenCode 1.18.x.

---

What OpenCode Is (and Why It Passed Claude Code)

OpenCode is an open-source, terminal-based AI coding agent — and as of August 2026 it is the most-starred coding agent on GitHub, at roughly 193K stars versus Claude Code's ~140K. It is MIT-licensed, works with any model provider, and connects to local models through Ollama.

If you have used Claude Code, OpenCode will feel immediately familiar: a terminal UI where you describe a task, and an agent plans, reads your files, edits them, and runs commands — with your approval gates in between. The difference is the model layer. Claude Code is built around Anthropic's models and pricing. OpenCode is provider-agnostic by design: its model catalog is powered by the Models.dev database, and any OpenAI-compatible endpoint works — which is exactly what Ollama exposes at localhost:11434/v1.

The numbers, checked on GitHub in August 2026: 193.4K stars, 24.7K forks, MIT license, and a release cadence that is honestly a little absurd — v1.18.11, v1.18.12, and v1.18.13 all shipped in the first four days of August. That speed is why this guide sticks to config that comes from the official docs rather than from months-old Reddit threads, and why we re-verify this page quarterly.

For local-first people, the pitch is simple: the top coding agent on GitHub, running against models on your own GPU, at exactly $0 per token. No seat license, no usage anxiety, no code leaving your machine during inference.

---

The 60-Second Setup

Two commands. Ollama's official OpenCode integration does the wiring for you.

Step 1 — install OpenCode (macOS/Linux):

curl -fsSL https://opencode.ai/install | bash

On Windows, the docs route is npm: npm install -g opencode-ai. Homebrew (brew install sst/tap/opencode), Scoop, Pacman, and Nix are also supported per the repo README.

Step 2 — pull a model and launch (this assumes Ollama is already installed; if not, start with our complete Ollama guide):

ollama pull qwen3-coder:30b
ollama launch opencode

ollama launch opencode is the shortcut Ollama's integration docs added — it starts OpenCode with the Ollama provider configured automatically, no JSON editing required. If it works for you, you are done with setup and can skip straight to the context-window section, because that part still applies to everyone.

If you would rather see (and control) exactly what is being configured — or the auto-setup does not detect your install — do it manually. It is one small file.

---

Manual opencode.json Config, Explained

Create opencode.json in your project root (or ~/.config/opencode/opencode.json globally) and declare Ollama as an OpenAI-compatible provider. This is the exact shape from OpenCode's official provider docs:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:30b": {
          "name": "Qwen3 Coder 30B (local)"
        }
      }
    }
  }
}

What each piece does, because you will eventually need to debug one of them:

• npm: "@ai-sdk/openai-compatible" — tells OpenCode to talk to this provider with the generic OpenAI-compatible adapter. Ollama's /v1 endpoint speaks that dialect, so no Ollama-specific plugin is needed.
• baseURL — Ollama's default port. If Ollama runs on another machine on your LAN (a common setup — the GPU box in the office, OpenCode on the laptop), put that machine's IP here and make sure Ollama is listening on 0.0.0.0.
• models — the keys must match your Ollama tags exactly (ollama list shows them). Each entry appears in OpenCode's model picker; add one per model you actually pulled.

Start OpenCode inside a project directory with opencode, pick your Ollama model from the model list, and give it a real task — "add input validation to the register endpoint and write a test for it" is a fair first test of whether the agent loop actually works on your hardware.

If it responds but never edits files, or edits garbage — do not switch models yet. Read the next section first, because the odds are high it is not the model.

---

The Context-Window Trap

Ollama's default context window is 4,096 tokens. OpenCode needs far more — Ollama's own integration docs say to use a 64K+ context — and when the window overflows, tool calling breaks silently. This is the single most common cause of "OpenCode doesn't work with local models" reports.

Here is why it breaks the way it does. An agent turn is not just your prompt: it is OpenCode's system prompt, the tool definitions, file contents it has read, and the conversation so far. At 4,096 tokens, that overflows almost immediately. Ollama then truncates from the top — which means the model loses the very instructions that tell it how to call tools. The failure mode is not an error message; it is a model that loops, re-reads the same file forever, or answers in prose instead of making edits. It looks like a dumb model. It is usually a starved one.

The fix is one environment variable when starting the Ollama server:

OLLAMA_CONTEXT_LENGTH=65536 ollama serve

(On a Mac menu-bar install, quit Ollama and relaunch from a terminal with the variable set, or set it via launchctl setenv. The /set parameter num_ctx command from Ollama's FAQ only applies inside an interactive ollama run session — it does not help a server that OpenCode talks to.)

Two calibration points from the official docs, since they disagree slightly: Ollama's OpenCode integration page says "OpenCode requires a context length of 64k or higher", while OpenCode's provider docs say that if tool calls are not working, increase num_ctx starting around 16K-32K. Read that as: 16-32K is where tool calling stops misbehaving, 64K is where the agent gets comfortable on multi-file tasks. The catch is memory — a bigger context means a bigger KV cache in VRAM, which is exactly what the next two sections are about.

If you are VRAM-tight, two more Ollama flags from its FAQ buy back real headroom: OLLAMA_FLASH_ATTENTION=1 (reduces memory growth as context grows), and OLLAMA_KV_CACHE_TYPE=q8_0, which Ollama documents as cutting KV-cache memory roughly in half with minimal precision loss.

---

Which Local Models Actually Work

For agentic editing in OpenCode, the field is narrower than "any coding model": you need solid tool calling AND a genuinely long context. As of August 2026 that shortlist is qwen3-coder:30b for 24GB+ setups and gpt-oss:20b for 16GB cards.

Specs below are from each model's Ollama library page, checked August 2026:

qwen3-coder:30b is the default recommendation for a reason. Its model card describes exactly the workload OpenCode generates: agentic coding, long-context repository understanding, pretraining with a 70% code ratio. The mixture-of-experts design is the practical magic — only 3.3B parameters are active per token, so it generates far faster than a dense 30B would, and it degrades relatively gracefully when Ollama has to offload some layers to CPU. Full details on the model family are in our Qwen3 Coder guide.

gpt-oss:20b is the 16GB-card answer. It was built with native function calling and structured outputs, ships in a quantization that targets 16GB-memory machines by design, and its 128K context clears OpenCode's bar with room to spare. It reasons out loud, which OpenCode displays — some people like watching the plan form, some find it chatty.

What about everything else in the Ollama library? Most older coder models fail one of the two tests. Plenty of well-liked models ship with native windows below what OpenCode wants, and small dense models (7B-8B class) tend to fumble multi-step tool sequences even when the context fits. They are fine for chat and autocomplete — our best Ollama models for agents roundup draws this line in more detail. For OpenCode specifically, start with the two above; go off-list only once you know what working feels like.

---

What Your GPU Can Run

Rule of thumb: the download size is roughly what the weights occupy in VRAM, and the 64K context you just configured adds a KV cache on top. Budget past the download number, not up to it.

The 24GB row deserves the extra sentence, because 3090 and 4090 owners are most of the audience: the weights fit with ~5GB to spare, and a 64K f16 KV cache is what pushes past the edge. In practice that means choosing between OLLAMA_KV_CACHE_TYPE=q8_0 (with flash attention on) to keep the large window, or dropping OLLAMA_CONTEXT_LENGTH to ~32K and letting OpenCode compact more often. Both are livable; overflowing into system RAM without noticing — and wondering why generation crawls — is the outcome to avoid.

We are deliberately not quoting tokens-per-second figures here: they swing hugely with quantization, context fill, and offload ratio, and numbers we have not measured on named hardware do not belong in a table. For weights-plus-context arithmetic on your specific card, our VRAM calculator does the math, and the hardware hub covers what to buy if this table just talked you into an upgrade.

---

OpenCode vs Claude Code (and the Other Local Agents)

OpenCode is the open-source, run-anything answer; Claude Code is the frontier-model specialist. In August 2026 the honest comparison is capability-for-cost, and stars-wise the student passed the teacher.

The capability caveat is real and belongs in this table's fine print: Claude Code driving a frontier Claude model will out-refactor qwen3-coder:30b on hard multi-file work — more on that below. What OpenCode wins is everything around that: license, provider freedom, and a $0 local mode with official support from the Ollama side. It is also possible to point Claude Code itself at local models — our Claude Code offline guide covers that route — but OpenCode is the tool that was built for it rather than bent into it.

Against the rest of the local coding field, the split is interface and autonomy. Continue.dev lives inside your editor — autocomplete and chat, you stay the driver. Cline is the agentic middle: a VS Code extension that plans and edits with approvals. Aider is the terminal pair-programmer with tight git discipline. OpenCode is the furthest toward full Claude-Code-style autonomy in a terminal — and, at the moment, the one with the most momentum behind it by a wide margin.

---

Where Local Models Fall Short

A local OpenCode setup is genuinely good at scoped tasks and genuinely worse than frontier models at large, entangled refactors. Anyone telling you otherwise is selling the dream, not describing the tool.

What holds up well in the local configuration this guide builds — and this matches the consensus across community reports on local agents, not just our read:

• Scoped, single-concern tasks. "Add a retry with backoff to this client," "write tests for this module," "fix this traceback." The agent loop plus a competent 30B-class coder handles these reliably.
• Codebase Q&A. With a 64K window, "where is auth actually enforced?" against a mid-sized repo works well — and privately.
• Boilerplate and glue. Scaffolding, config wiring, test skeletons: high volume, low ambiguity, ideal local work.

What still favors the frontier:

• Multi-file refactors with entangled dependencies. This is the widely-reported gap between local and frontier agents, and our experience agrees: qwen3-coder-class models lose the thread across many coordinated edits more often than Claude-class models do. Smaller effective context and weaker long-horizon planning both contribute.
• Long agent sessions. Local models degrade as compaction kicks in; frontier models degrade later and recover better.
• Ambiguity. Underspecified tasks get better clarifying behavior from frontier models. Local models more often guess — confidently.

Freshness caveat, stated plainly: OpenCode shipped three releases in the four days before this was written. Config syntax and behavior can drift. Everything here matches the official docs as of early August 2026, and we re-verify quarterly — if something breaks in the meantime, opencode.ai/docs is the source of truth and usually ahead of every tutorial on the internet, including this one.

The mature take: run both. Local OpenCode for the 80% of daily work that is scoped, private, and constant; a frontier model for the 20% that is genuinely hard. The 80% costing $0 forever is the point.

---

Sources

• OpenCode GitHub repository — stars, forks, MIT license, install methods (checked August 2026)
• OpenCode provider docs — the opencode.json Ollama config and the num_ctx tool-calling guidance
• Ollama OpenCode integration docs — ollama launch opencode and the 64K+ context requirement
• Ollama FAQ — the 4,096-token default, OLLAMA_CONTEXT_LENGTH, flash attention, and KV-cache quantization
• qwen3-coder and gpt-oss Ollama model cards — tags, download sizes, context windows, pull counts
• Claude Code GitHub repository — star count for the comparison (checked August 2026)

---

FAQ