OpenCode + Ollama: run OpenCode on a local model
12 min read
Run OpenCode on a local model with Ollama: the one-command launch, automatic discovery in OpenCode 2, the opencode.json provider block, models and limits.
OpenCode can run against a model that Ollama serves on your own machine. One command, ollama launch opencode, starts it, and OpenCode 2 also finds a running Ollama server at http://127.0.0.1:11434 by itself and lists its models under /models, with no account and no API key.
You need Ollama 0.15 or later for the launch command, a model that supports tool calling, a context length of 64K tokens, and 16 GB of memory or more, depending on the model. This guide gives the one-command path, automatic discovery, the manual opencode.json provider block, how to check that requests stay local, the known limits, and how to roll the same setup out to a team with Aventail™ Connect.
What you need
Minimum | Comfortable | |
|---|---|---|
Ollama | 0.15 for | Latest release: 0.40.16, published 9 November 2026 |
OpenCode | OpenCode 1 with a manual provider block | OpenCode 2 for automatic discovery; 2.3.0 was released on 13 November 2026 |
Context length | 64K tokens. Ollama's OpenCode page says OpenCode requires 64K or higher | The model's full window, if it fits in memory |
Memory (unified or VRAM) | 16 GB for gpt-oss:20b | About 23 GB of VRAM for glm-4.7-flash at 64K context, by Ollama's figure |
Disk | 14 to 20 GB per model | Space for two or three models |
Ollama sets a default context length from your GPU memory: 4K below 24 GiB, 32K from 24 to 48 GiB, 256K at 48 GiB and above. With less than 24 GiB of GPU memory that is 4K, which is too small for an agent, so you raise it by hand in step 1.
Step 1: install Ollama and set the context length
macOS and Linux:
curl -fsSL https://ollama.com/install.sh | sh
Windows PowerShell:
irm https://ollama.com/install.ps1 | iex
Set the context length before you serve a model. The quickest way is the slider in the Ollama app settings. From a terminal:
OLLAMA_CONTEXT_LENGTH=64000 ollama serve
Check what is loaded, how much context it has, and whether it sits on the GPU or the CPU:
ollama ps
The CONTEXT column shows the allocated length and the PROCESSOR column shows the GPU and CPU split. If part of the model has spilled to the CPU, pick a smaller model or a shorter context.
Step 2: pull a model that supports tools
OpenCode reads files, edits them and runs commands through tool calls. A model without tool support will chat and do nothing else. Every model below carries the tools tag in the Ollama library on 15 November 2026.
Model | Size on disk | Context window | Memory guidance from Ollama | Tags |
|---|---|---|---|---|
gpt-oss:20b | 14 GB | 128K | Runs on systems with as little as 16 GB | tools, thinking |
qwen3-coder:30b | 19 GB | 256K | Not published for the 30B size | tools |
glm-4.7-flash | 19 GB | 198K | About 23 GB of VRAM at 64K context | tools, thinking |
devstral-small-2:24b | 15 GB | 384K | Not published | tools, vision |
qwen3.5:27b | 17 to 20 GB | 256K | Not published | tools, thinking, vision |
gemma4:26b | 16 to 19 GB | 256K | Not published | tools, thinking, vision |
Where Ollama publishes no memory figure, use the file size as the floor: the weights and the 64K context both have to fit in memory. A 19 GB model does not fit on a 16 GB machine.
ollama pull qwen3-coder:30b
Step 3: install OpenCode
OpenCode's own docs give these commands for version 2:
curl -fsSL https://opencode.ai/v2/install | bash
npm install -g @opencode/cli
On Windows, OpenCode says Windows package managers are not supported. Download the standalone binary or the desktop app from the OpenCode docs. Ollama's integration page still lists the older commands curl -fsSL https://opencode.ai/install | bash and npm install -g opencode-ai.
OpenCode 1 and OpenCode 2 both use the opencode command and are not installed side by side by default.
Step 4: launch OpenCode on Ollama with one command
ollama launch opencode
Ollama asks which model to use and starts OpenCode pointed at the local server. To skip the picker, name the model:
ollama launch opencode --model qwen3-coder:30b
To configure OpenCode for Ollama without starting an interactive session:
ollama launch opencode --config
ollama launch opencode starts OpenCode with an inline config for the selected model. It does not overwrite ~/.config/opencode/opencode.json, and your existing OpenCode settings still apply. Models that you define only in opencode.json do not appear in the launch picker.
Step 5: or let OpenCode 2 find Ollama by itself
With Ollama running and a model pulled, start OpenCode from its own command:
opencode
OpenCode 2 probes http://127.0.0.1:11434, discovers the models that can generate text, and adds them to /models under the ollama provider ID. It reads context, vision and tool-use capabilities from Ollama and refreshes the list in the background. Embedding-only models do not appear.
To make a local model the default for new sessions, put this in ~/.config/opencode/opencode.json or in opencode.json in the project:
{ "$schema": "https://opencode.ai/config.json", "model": "ollama/qwen3-coder:30b"}
If Ollama runs on another host or port, set its OpenAI-compatible URL. Include /v1. OpenCode derives the native discovery paths from it, and apiKey is optional:
{ "$schema": "https://opencode.ai/config.json", "providers": { "ollama": { "settings": { "baseURL": "https://ollama.example.com/v1", "apiKey": "{env:OLLAMA_API_KEY}" } } }}
Step 6: or write the provider block by hand
Use this on OpenCode 1, or when you want to list the models yourself. This is the block Ollama's docs give:
{ "$schema": "https://opencode.ai/config.json", "provider": { "ollama": { "npm": "@ai-sdk/openai-compatible", "name": "Ollama", "options": { "baseURL": "http://localhost:11434/v1" }, "models": { "qwen3.5": { "name": "qwen3.5" } } } }}
Three things to know about it:
It is the OpenCode 1 format. OpenCode 2 still reads it. In the native OpenCode 2 format
providerbecomesproviders,npmbecomespackage, andoptions.baseURLbecomessettings.baseURL.The model key must match the Ollama name. Use the name that
ollama lsprints, including the tag.State the real context length on OpenCode 2. For a model that is not in its catalogue, OpenCode 2 assumes a 200,000-token context limit and a 32,000-token output limit. If Ollama has allocated 64K, OpenCode will compact too late. Set
limit.contexton the model to the length you gave Ollama.
The native OpenCode 2 version, using OpenCode's recipe for an OpenAI-compatible server with Ollama's address and a stated limit:
{ "$schema": "https://opencode.ai/config.json", "model": "local/coder", "providers": { "local": { "name": "Local server", "package": "@opencode/ai/providers/openai-compatible", "settings": { "baseURL": "http://127.0.0.1:11434/v1" }, "models": { "coder": { "modelID": "qwen3-coder:30b", "capabilities": { "tools": true, "input": ["text"], "output": ["text"] }, "limit": { "context": 64000, "output": 8192 } } } } }}
Step 7: check it is running locally
Run
ollama pswhile OpenCode is answering. The model should be listed with the context length you set.In OpenCode, open
/modelsand confirm the active model starts withollama/. If you never set a default, OpenCode falls back to the newest available supported model, which can be one of OpenCode's free hosted models.Make Ollama the only provider OpenCode may use. OpenCode 2 policies are evaluated in order and the last match wins:
{"$schema": "https://opencode.ai/config.json","policies": [{ "action": "provider.use", "resource": "*", "effect": "deny" },{ "action": "provider.use", "resource": "ollama", "effect": "allow" }]}If you use a custom provider ID such as
localfrom step 6, allow that ID instead.Set
"update": "disable"in the global config if you want OpenCode to skip update checks.Unplug the network and ask OpenCode to explain a file. If it answers, the model is local.
Web search is a separate path. OpenCode asks before the first search and uses a search provider you choose, so decline it if nothing may leave the machine.
What works and what does not on a local model
Ollama lists these OpenCode capabilities: chat, running commands, file edits, subagents, web fetch and vision.
Known limits:
Tool calling depends on the model. Pick a model with the
toolstag. OpenCode 1's docs add a tip: if tool calls are not working, increase the context length in Ollama. Expect more retries and the odd malformed edit than with a frontier hosted model.tool_choiceis not supported on Ollama's/v1/chat/completionsendpoint, so a client cannot force a specific tool.The default context is too small. Below 24 GiB of VRAM Ollama allocates 4K unless you change it. OpenCode's docs do not say whether the context it reads from Ollama is the model's maximum or the allocated length, so check
ollama ps.Compaction comes sooner. OpenCode summarises the conversation when it nears the context limit and keeps about 15,000 recent tokens. It is on by default and it is lossy. With a 64K window it starts much earlier in a session than with a 200K window.
No prompt-cache controls. OpenCode places cache breakpoints for providers that need them, such as Anthropic. Ollama's OpenAI-compatible API documents no cache settings. On a local model the cost of a long conversation is time.
Speed and timeouts. Neither vendor publishes tokens per second for these pairings. OpenCode waits up to five minutes for response headers and fifteen minutes between streamed chunks, then retries up to three times. If a large model takes longer than that to load and start answering, raise
settings.headerTimeouton the provider.
Ollama cloud models are not your own models
Ollama also offers :cloud models and a hosted endpoint at ollama.com. Ollama states that prompt and response data is never logged or trained on, and that it hosts models primarily in the United States with routing to Europe for extra capacity. They are still a third party's servers. If your code must stay on your machines, do not pick a :cloud name in the launch picker, and keep baseURL on localhost.
The same setup for a team with Aventail™ Connect
The steps above suit one developer who manages their own machine. They give an IT or security lead no record of which machine sent which request where, and no rule that a developer cannot edit back in opencode.json.
Aventail™ Connect configures supported apps to send their model requests through Aventail™ Link, the inference engine and gateway that runs on each machine. Routing rules are set in Aventail™ Control and evaluated on the device. OpenCode, Claude Code, Claude Desktop and Codex are supported. In this setup Link serves the model itself, in place of Ollama.
Sign in to Control at control.aventail.co.uk and choose Connect a device.
Install Link on each machine: desktop installers for macOS (Apple silicon), Windows x64 and Linux x64, or unattended:
curl -fsSL https://get.aventail.co.uk/install.sh | AVENTAIL_REGISTRATION_KEY='YOUR_REG_KEY' shServe a model. In Models, download a coding model and choose Start serving. Check that it supports coding tools and has enough context.
Connect OpenCode. In Connected apps, choose Connect next to OpenCode. There is no provider entry, endpoint or key to write. OpenCode 2 picks the settings up while running; OpenCode 1 needs a restart. Review any provider you added to OpenCode by hand so it does not conflict.
Check where it ran. Send a harmless prompt, then open Requests in Control.
Write the routing rule. The first matching enabled rule wins. For a local-only team, permit only On device; if local serving is unavailable, the request fails with an error.
Disconnect restores the settings Link changed. The Free plan covers three connected devices, including business use. Starter is £50 a month excluding VAT and includes ten devices. Routing policies need Control for Enterprise.
Which path to take
OpenCode + Ollama by hand | OpenCode with Aventail™ Connect | |
|---|---|---|
Who it suits | One developer on their own machine | A team whose code must stay on approved models |
Setup |
| Connect button in Link, rules in Control |
Who picks the model | The developer, in | The developer in Link, within the routing rule |
Where requests go | Wherever the OpenCode config says | Where the routing rule says, evaluated on the device |
Record of requests | None | Requests view in Control |
If the local model is down | Developer picks another provider | Fails with an error, or falls back to an approved provider |
Cost | Free | Free for three devices; £50 a month for ten |
Frequently asked questions
Does OpenCode work with Ollama?
Yes. Ollama documents ollama launch opencode, and OpenCode 2 discovers a local Ollama server at http://127.0.0.1:11434 and lists its models under the ollama provider.
Is OpenCode free to use with Ollama?
Yes. OpenCode is open source under the MIT licence and a local Ollama model has no per-token charge. You pay for the hardware and the electricity.
Which Ollama model is best for OpenCode?
On 16 GB, gpt-oss:20b. With more memory, qwen3-coder:30b, glm-4.7-flash or devstral-small-2. The deciding factor is tool-calling reliability, so test the model on a real edit before you settle. Our guide to the best local LLMs for coding compares them.
Where does the OpenCode config file go?
User settings for every project go in ~/.config/opencode/opencode.json or opencode.jsonc. Project settings go in opencode.json in the project, or in .opencode/opencode.json. The project file overrides the global one.
Why does OpenCode chat but not edit files with my Ollama model?
The usual causes are a model without tool support and a context length that is too small. Check the tools tag on the model's library page, then check the CONTEXT column in ollama ps. It should read 64000 or more.
Can OpenCode use Ollama on another computer?
Yes. Set providers.ollama.settings.baseURL to that server's address with /v1 at the end. Add apiKey if the server sits behind a proxy that needs a bearer token.
Does OpenCode work offline with Ollama?
Model requests do, once the model is pulled. Set "update": "disable" so OpenCode stops checking for updates, and do not use web search.
Related guides
OpenCode + LM Studio
Sources
Ollama, OpenCode integration: https://docs.ollama.com/integrations/opencode
Ollama, Context length: https://docs.ollama.com/context-length
Ollama, CLI reference: https://docs.ollama.com/cli
Ollama, OpenAI compatibility: https://docs.ollama.com/api/openai-compatibility
Ollama blog, ollama launch (23 January 2026): https://ollama.com/blog/launch
Ollama download page and releases (v0.40.16): https://ollama.com/download and https://github.com/ollama/ollama/releases/latest
Ollama library: gpt-oss, qwen3-coder, glm-4.7-flash, devstral-small-2, qwen3.5, gemma4 at https://ollama.com/library
Ollama cloud: https://ollama.com/cloud
OpenCode, Intro and install: https://opencode.ai/docs/
OpenCode, Providers: https://opencode.ai/docs/providers/
OpenCode, Models: https://opencode.ai/docs/models/
OpenCode, Config: https://opencode.ai/docs/config/
OpenCode, Migrate from V1: https://opencode.ai/docs/migrate-v1/
OpenCode, Policies: https://opencode.ai/docs/policies/
OpenCode, Compaction: https://opencode.ai/docs/compaction/
OpenCode, Web search: https://opencode.ai/docs/websearch/
OpenCode 1 docs, Providers: https://opencode.ai/v1/docs/providers
OpenCode changelog, v2.3.0: https://opencode.ai/changelog
Aventail™, Connect overview: https://docs.aventail.co.uk/docs/connect/overview
Aventail™, Initial setup: https://docs.aventail.co.uk/docs/getting-started/initial-setup
Aventail™, Routing: https://docs.aventail.co.uk/docs/fleet/routing
Aventail™, Pricing: https://aventail.co.uk/#pricing
All sources were read on 15 November 2026.