Skip to content
Aventail™ investigation into UK government AI dependence featured in Computer Weekly.Read the story
Aventail™
All guides

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 ollama launch (announced 23 January 2026)

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 provider becomes providers, npm becomes package, and options.baseURL becomes settings.baseURL.

  • The model key must match the Ollama name. Use the name that ollama ls prints, 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.context on 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

  1. Run ollama ps while OpenCode is answering. The model should be listed with the context length you set.

  2. In OpenCode, open /models and confirm the active model starts with ollama/. 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.

  3. 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 local from step 6, allow that ID instead.

  4. Set "update": "disable" in the global config if you want OpenCode to skip update checks.

  5. 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 tools tag. 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_choice is not supported on Ollama's /v1/chat/completions endpoint, 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.headerTimeout on 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.

  1. Sign in to Control at control.aventail.co.uk and choose Connect a device.

  2. 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' sh

  3. Serve a model. In Models, download a coding model and choose Start serving. Check that it supports coding tools and has enough context.

  4. 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.

  5. Check where it ran. Send a harmless prompt, then open Requests in Control.

  6. 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

ollama launch opencode, discovery, or opencode.json

Connect button in Link, rules in Control

Who picks the model

The developer, in /models

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.

Sources

  1. Ollama, OpenCode integration: https://docs.ollama.com/integrations/opencode

  2. Ollama, Context length: https://docs.ollama.com/context-length

  3. Ollama, CLI reference: https://docs.ollama.com/cli

  4. Ollama, OpenAI compatibility: https://docs.ollama.com/api/openai-compatibility

  5. Ollama blog, ollama launch (23 January 2026): https://ollama.com/blog/launch

  6. Ollama download page and releases (v0.40.16): https://ollama.com/download and https://github.com/ollama/ollama/releases/latest

  7. Ollama library: gpt-oss, qwen3-coder, glm-4.7-flash, devstral-small-2, qwen3.5, gemma4 at https://ollama.com/library

  8. Ollama cloud: https://ollama.com/cloud

  9. OpenCode, Intro and install: https://opencode.ai/docs/

  10. OpenCode, Providers: https://opencode.ai/docs/providers/

  11. OpenCode, Models: https://opencode.ai/docs/models/

  12. OpenCode, Config: https://opencode.ai/docs/config/

  13. OpenCode, Migrate from V1: https://opencode.ai/docs/migrate-v1/

  14. OpenCode, Policies: https://opencode.ai/docs/policies/

  15. OpenCode, Compaction: https://opencode.ai/docs/compaction/

  16. OpenCode, Web search: https://opencode.ai/docs/websearch/

  17. OpenCode 1 docs, Providers: https://opencode.ai/v1/docs/providers

  18. OpenCode changelog, v2.3.0: https://opencode.ai/changelog

  19. Aventail™, Connect overview: https://docs.aventail.co.uk/docs/connect/overview

  20. Aventail™, Initial setup: https://docs.aventail.co.uk/docs/getting-started/initial-setup

  21. Aventail™, Routing: https://docs.aventail.co.uk/docs/fleet/routing

  22. Aventail™, Pricing: https://aventail.co.uk/#pricing

All sources were read on 15 November 2026.

We use optional cookies and tracking to identify visiting companies, load our contact form, measure Google Ads download clicks and understand page use with PostHog on our homepage, Connect and How it works pages, Ollama and LM Studio comparison guides and campaign pages. Cookie policy