---
title: "OpenCode + Ollama: run OpenCode on a local model — Aventail™ Guides"
url: https://aventail.co.uk/guides/opencode-ollama
description: "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."
lang: en-GB
---

Skip to content

Aventail™ investigation into UK government AI dependence featured in Computer Weekly. Read the story: https://aventail.co.uk/newsroom/computer-weekly-uk-government-ai-dependency

All guides (https://aventail.co.uk/guides)

# OpenCode + Ollama: run OpenCode on a local model

16 November 2026 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 (https://aventail.co.uk/guides/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

- AI coding on your own models: https://aventail.co.uk/guides/ai-coding-on-your-own-models
- Claude Code + Ollama: https://aventail.co.uk/guides/claude-code-ollama
- Codex + Ollama: https://aventail.co.uk/guides/codex-ollama
- OpenCode + LM Studio
- OpenCode with: https://aventail.co.uk/guides/opencode-with-aventail-connect
  Aventail: https://aventail.co.uk/guides/opencode-with-aventail-connect
  ™: https://aventail.co.uk/guides/opencode-with-aventail-connect Connect: https://aventail.co.uk/guides/opencode-with-aventail-connect
- OpenCode vs Claude Code: https://aventail.co.uk/guides/opencode-vs-claude-code

## 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 (https://aventail.co.uk/cookies)

## Structured data

```json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://aventail.co.uk/#organization",
      "name": "Aventail",
      "alternateName": "Locai",
      "legalName": "Loc.ai Ltd",
      "description": "Aventail, formerly Locai, was founded in 2026 and is a graduate of Google AI First. It gives enterprises the full AI stack to adopt AI securely: a built-in inference engine, deployment of supported models across approved hardware, on-device classification and policy-based routing between those machines and approved external AI providers, central management and an employee workspace. Organisations use Aventail to put approved information to work while controlling where inference requests run.",
      "url": "https://aventail.co.uk/",
      "logo": "https://aventail.co.uk/apple-touch-icon.png",
      "email": "hello@aventail.co.uk",
      "hasCredential": [
        {
          "@type": "EducationalOccupationalCredential",
          "name": "Cyber Essentials",
          "credentialCategory": "certification",
          "url": "https://aventail.co.uk/trust#cyber-essentials"
        }
      ]
    },
    {
      "@type": "Article",
      "@id": "https://aventail.co.uk/guides/opencode-ollama#page",
      "url": "https://aventail.co.uk/guides/opencode-ollama",
      "name": "OpenCode + Ollama: run OpenCode on a local model",
      "description": "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.",
      "publisher": {
        "@id": "https://aventail.co.uk/#organization"
      },
      "headline": "OpenCode + Ollama: run OpenCode on a local model",
      "datePublished": "2026-11-16",
      "dateModified": "2026-11-16T18:48:12.650806+00:00",
      "image": "https://aventail-ai-platform.lovable.app/images/share/og-home-v7.jpg",
      "author": {
        "@id": "https://aventail.co.uk/#organization"
      }
    },
    {
      "@type": "BreadcrumbList",
      "@id": "https://aventail.co.uk/guides/opencode-ollama#breadcrumb",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Home",
          "item": "https://aventail.co.uk/"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Guides",
          "item": "https://aventail.co.uk/guides"
        },
        {
          "@type": "ListItem",
          "position": 3,
          "name": "OpenCode + Ollama: run OpenCode on a local model",
          "item": "https://aventail.co.uk/guides/opencode-ollama"
        }
      ]
    }
  ]
}
```