OpenCode + Ollama Setup Guide 2026: Local Coding Agent

By AIFoss · 11 min read
opencodeollamacoding-agentselfhostedai

TL;DR: OpenCode is a terminal-native coding agent (MIT, ~183K stars) that talks to any OpenAI-compatible endpoint. Point it at a local Ollama model and you get a Claude Code-style agent with zero per-token cost. The catch: local 7B–32B models lag cloud frontier models on multi-file refactors, and you must use a tool-calling-capable model or the agent silently does nothing.

OpenCode + OllamaCline + OllamaContinue.dev + Ollama
InterfaceTerminal (TUI)VS Code extensionVS Code / JetBrains
Best forCLI-first devs, servers, SSHFull IDE agent workflowsInline completion + chat
Local cost$0$0$0
The catchNo GUI; needs tool-calling modelHeavier; editor-boundWeaker as a standalone agent

Honest take: If you live in the terminal and want a provider-agnostic agent you can wire to a local model in five minutes, OpenCode is the one to install. For an in-editor experience, use Cline instead.

Cloud coding agents are convenient until the bill arrives. A $20/month subscription is $240 a year, and the metered API tiers climb faster than that if you actually use them. OpenCode removes the meter entirely: it runs in your terminal, connects to whatever model backend you point it at, and when that backend is a local Ollama instance, every token is free and nothing leaves your machine.

Here is the full setup, the config file that actually works, and the two mistakes that make people give up in the first ten minutes.

What OpenCode is (and who builds it)

OpenCode is an open-source, terminal-native AI coding agent maintained by Anomaly Co (the anomalyco GitHub org, built by the team formerly behind SST). It is MIT-licensed — you can read, fork, and self-host the entire thing with no commercial restrictions. As of July 2026 the repo sits at roughly 183,000 stars, and the latest release is v1.17.13 (July 1, 2026).

It is model-agnostic by design: OpenCode supports 75+ providers, from Anthropic and OpenAI to local runners. It ships two built-in agents — build (writes and edits code) and plan (read-only reasoning) — that you switch between with the Tab key, plus a general subagent for delegated tasks. It also connects to MCP servers, the same tool-integration protocol Claude Code uses, so your existing MCP setup carries over.

The reason it matters for self-hosters: OpenCode treats a local Ollama endpoint the same as any cloud provider. One config block and you have swapped a paid API for a model running on your own GPU.

What you’ll have running after this guide

  • OpenCode installed and launching from any project directory
  • A local Ollama model wired in as a first-class provider, selectable at runtime
  • A tested opencode.json you can copy to any machine, with zero API keys and zero outbound traffic

Step 1 — Install Ollama and pull a tool-calling model

If you already run Ollama, skip to the model pull. Otherwise, install it and confirm the server is up:

# Linux / macOS
curl -fsSL https://ollama.com/install.sh | sh

# confirm the daemon is listening
ollama --version
# ollama version is 0.30.10

The model choice matters more than anything else in this guide. OpenCode is an agent — it works by calling tools (read file, write file, run command). If the model was not trained for tool use, OpenCode will connect fine, accept your prompt, and then do nothing. Pick a coding model with tool-calling support. Qwen3-Coder is the reliable default:

# 30B variant — needs a 24GB GPU at Q4, strong tool-calling
ollama pull qwen3-coder:30b

# smaller fallback for 12–16GB cards
ollama pull qwen3-coder:7b

Confirm it loaded and note the size:

ollama list
# NAME                 ID           SIZE      MODIFIED
# qwen3-coder:30b      a1b2c3d4     18 GB     10 seconds ago

For the deeper model-selection tradeoffs and quantization math on a single 24GB card, see the Qwen3-Coder-Next local setup guide.

Step 2 — Install OpenCode

Two supported install paths. The install script is the simplest:

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

# or via npm if you prefer to manage it yourself
npm i -g opencode-ai@latest

Launch it once from inside a git project to confirm it starts:

cd ~/code/my-project
opencode

You will land in the TUI. It will complain that no model is configured — that is expected. Quit with Ctrl+C and move to the config.

Step 3 — The opencode.json that works

OpenCode reads config from ~/.config/opencode/opencode.json (global) or opencode.json in a project root (per-project, takes precedence). Local models are added as a custom provider using the @ai-sdk/openai-compatible package. Ollama exposes an OpenAI-compatible API at http://localhost:11434/v1, so the block is short:

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

Three things about this file:

  • The top-level "model" sets the default. The format is provider/model-id — here ollama/qwen3-coder:30b.
  • Every model you want to select must be listed in the models block. OpenCode does not auto-discover the models Ollama has pulled; you name them explicitly.
  • No API key. Ollama does not require one, and OpenCode does not send one for a local openai-compatible provider.

Save the file, then relaunch OpenCode. Config changes are not picked up while OpenCode is running — you have to fully restart the app after editing opencode.json. This trips up nearly everyone the first time.

opencode
# then press /models to confirm "Qwen3 Coder 30B" appears and is selected

Ask it something concrete to confirm the full loop works:

> read package.json and tell me what test runner this project uses

If the agent reads the file and answers, tool-calling is wired correctly. If it hangs or replies without reading anything, jump to the troubleshooting section — that is the tool-calling trap.

Step 4 — Add LM Studio or vLLM (optional)

The same pattern covers any OpenAI-compatible backend. If you serve models through LM Studio or vLLM instead of (or alongside) Ollama, add another provider block with the right port:

"provider": {
  "lmstudio": {
    "npm": "@ai-sdk/openai-compatible",
    "name": "LM Studio",
    "options": { "baseURL": "http://localhost:1234/v1" },
    "models": { "qwen3-coder-30b": { "name": "Qwen3 Coder (LM Studio)" } }
  },
  "vllm": {
    "npm": "@ai-sdk/openai-compatible",
    "name": "vLLM",
    "options": { "baseURL": "http://localhost:8000/v1" },
    "models": { "Qwen/Qwen3-Coder-30B": { "name": "Qwen3 Coder (vLLM)" } }
  }
}

vLLM gives you far higher throughput than Ollama for multi-user or batched workloads — the tradeoff is setup complexity. If you are serving a team, that is the right backend; the vLLM setup guide covers it end to end.

The problem everyone hits: the agent connects but does nothing

Two failure modes account for almost every “OpenCode + Ollama doesn’t work” report:

1. The model can’t call tools. A plain chat model (say, a base llama3 or a generic instruct model) will connect through the OpenAI-compatible endpoint and respond to messages, but it cannot invoke OpenCode’s file and shell tools. The agent appears “dumb” — it talks but never edits. Fix: use a model explicitly built for tool use. Qwen3-Coder, and other coding-tuned models with function-calling support, work out of the box. If you must use a general model, verify it advertises tool-calling before blaming OpenCode.

2. The context window is too small. Ollama defaults many models to a 4096-token context. Coding agents blow past that instantly — a single file plus the system prompt can exceed it — and the model starts truncating silently, producing broken edits or forgetting the task mid-run. Fix: raise num_ctx. Create a Modelfile or set it per-model in Ollama so the agent has room to work:

# raise the context window to 32k for the coder model
cat > Modelfile <<'EOF'
FROM qwen3-coder:30b
PARAMETER num_ctx 32768
EOF
ollama create qwen3-coder:30b-32k -f Modelfile

Then point opencode.json at qwen3-coder:30b-32k. This one change is the difference between an agent that edits three files coherently and one that falls apart on the second turn. Watch your VRAM — a larger context costs memory, and on a 24GB card you may need to drop to a smaller quant or the 7B model to fit 32k comfortably. For sizing headroom against context length, the local LLM context window guide has the VRAM math.

A note on :cloud model tags

Ollama v0.30+ introduced :cloud-suffixed tags like qwen3-coder:480b-cloud. These do not run on your GPU — they route inference to Ollama’s own servers. The API surface is identical, so it is easy to configure one by accident and assume you are fully local when your prompts are actually leaving the machine. If privacy is the point of self-hosting, use tags without the :cloud suffix and confirm with ollama ps that the model is loaded into your local VRAM during a request.

When NOT to use OpenCode + local models

Local coding agents are a cost-and-privacy play, not a capability play. Be honest about where they fall short:

  • Complex multi-file refactors. A 7B–32B local model lags cloud frontier models (GPT-5.5, Fable 5, Claude Opus) on tasks that span many files and require holding a large mental model. If correctness on a hard refactor matters more than cost, a cloud agent still wins.
  • You live in an IDE, not a terminal. OpenCode is TUI-first. If you want inline diffs and click-to-accept inside VS Code, Cline or Continue.dev fit better.
  • You lack the GPU. A usable coding model needs a 12GB card minimum for 7B and 24GB for 30B at reasonable context. If you are on integrated graphics or a laptop, renting a RunPod GPU by the hour is cheaper than buying hardware you will use occasionally. For a buy-vs-rent breakdown, see runaihome’s local AI hardware guides.
  • Team scale. Ollama is single-stream. For several developers hitting one backend, move to vLLM or a dedicated server.

For a broader look at where every open-source coding agent stands in 2026, the open-source coding agents state of play compares Aider, Cline, OpenCode, and the rest on maturity and local-model support. If you are evaluating cloud tools too, aicoderscope covers the Cursor and Cline paid tiers.

FAQ

Is OpenCode really free? The software is MIT-licensed and free to use, modify, and self-host. When paired with local Ollama models the runtime cost is zero — no API keys, no per-token billing. You only pay for electricity and the GPU you already own.

Which local model should I use with OpenCode? A coding model with tool-calling support. Qwen3-Coder is the safe default — the 30B variant on a 24GB GPU, or the 7B on a 12–16GB card. Avoid plain chat models; they connect but can’t drive the agent’s tools.

Why does the agent respond but never edit files? Almost always because the model can’t call tools, or num_ctx is too small and context is being truncated. Switch to a tool-calling coding model and raise the context window to at least 32k. Both fixes are in the troubleshooting section above.

Do I need an API key for Ollama? No. Ollama’s local endpoint requires no authentication, and OpenCode does not send a key for a local openai-compatible provider. Leave the key out of the config entirely.

Does OpenCode work with MCP servers? Yes. OpenCode connects to the same MCP servers Claude Code uses, so tool integrations you already run carry over. Add them in the same opencode.json config file.

How is OpenCode different from Aider or Cline? OpenCode is terminal-native and provider-agnostic with two-agent (build/plan) switching. Aider is also CLI-based but patch-focused; Cline is a VS Code extension. All three run free on local models — the choice is about where you work, not cost.

Sources

Was this article helpful?