OpenCode Ollama Setup: 7 Checks for Local Models

Quick verdict: start with launch, keep config for repeatability

For a first test, the official Ollama path is the quickest: run `ollama launch opencode`, choose a model, and let the integration open OpenCode with the selected local or cloud model. That path reduces mistakes because you are not hand-writing provider fields before you know whether the machine, model, and terminal workflow feel usable.

For a durable setup, keep a written `opencode.json` pattern. A config file makes the provider endpoint, model name, and permission assumptions reviewable in Git or in a team note. It also helps when one machine works and another fails, because you can compare the exact base URL, model alias, and runtime version instead of relying on memory.

The practical rule is simple: use the launch command to prove the integration, then document the stable configuration once you know which model and repository workflow are worth keeping.

Ollama setup decision table

Do not choose the setup method by ideology. Choose it by the job. A solo developer testing a laptop model needs speed; a team that wants reproducible local AI coding needs a config shape, validation notes, and a rollback path.

This is also the keyword boundary for the page. General OpenCode installation remains on the deployment guide, OpenCode vs Claude Code remains on the comparison page, and session file cleanup remains on the session storage page. The new intent here is specifically OpenCode plus Ollama provider setup.

Before you connect OpenCode to Ollama

Check the local model separately before involving OpenCode. Install Ollama, pull a coding-capable model, and run one direct prompt from the terminal. If the model is too slow, cannot load, or runs out of memory in a simple chat, OpenCode will not magically fix it during a repository edit.

Pick a small repository for the first validation. The ideal test has Git history, a README, one small bug or documentation task, and a harmless command such as a formatter or unit test. Avoid production migrations, deployment scripts, secret files, or customer data until the local model proves it can follow instructions and produce reviewable diffs.

Be realistic about hardware. Local models trade provider cost and data locality for memory pressure and slower response time. Smaller models can be useful for explanation and lightweight edits, while larger coding models may need more VRAM or a remote GPU host.

7 checks for a reliable OpenCode Ollama workflow

These checks keep the setup practical. The goal is not to prove that local models are always better; the goal is to know exactly where the chain works or breaks: Ollama service, model loading, OpenCode provider wiring, repository context, edit quality, and command approval.

1. Confirm the service Run Ollama directly and make sure the default local service is reachable before opening OpenCode.
2. Pull the model Use a model that is appropriate for coding and fits your memory budget.
3. Choose launch or config Use `ollama launch opencode` for the first proof, then document `opencode.json` if the workflow will be reused.
4. Select the model in OpenCode Open the model picker or equivalent provider selection and confirm the Ollama model is visible.
5. Run a read-only task Ask OpenCode to summarize a small file before allowing edits.
6. Run a low-risk edit Change documentation or a test fixture and inspect the Git diff.
7. Record failure notes Save the model name, port, OS, shell, and fix for any timeout, missing model, or spawn error.

Example opencode.json shape for Ollama

The exact configuration may change as OpenCode and Ollama evolve, so verify commands against official docs before standardizing them. The stable idea is that OpenCode treats Ollama as a local provider through an OpenAI-compatible endpoint, commonly on `http://localhost:11434/v1`.

Keep secrets out of the file. A local Ollama endpoint normally does not need a provider API key, but the same repository may also define cloud providers. Do not mix local provider examples with real production tokens.

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

Troubleshooting: isolate the failing layer

If OpenCode cannot see the model, first confirm Ollama can run it directly. Then check whether the local server is listening, whether the base URL includes the right path, and whether the selected model name matches what Ollama exposes. Changing three settings at once usually makes the failure harder to reproduce.

If the model answers but edits are poor, the issue may not be installation. Try a smaller task, reduce the repository scope, or use a stronger model for code edits and keep the local model for explanation. Local does not automatically mean best for every coding job.

If a remote Ollama server is involved, treat it like infrastructure. Confirm host reachability, firewall rules, authentication expectations, latency, and whether you are exposing a model endpoint beyond the trusted network. A private local endpoint is different from a public model server.

When not to use Ollama as your default OpenCode provider

Do not make Ollama the default just because it is local. If your repository is large, the model context is too small, or the hardware makes every edit painfully slow, a cloud model may be the more reliable default while Ollama remains useful for private exploration and offline explanation.

Avoid local-only workflows when the team cannot support them. Someone must own the model choice, hardware notes, update cadence, and troubleshooting path. Otherwise every developer ends up with a different local assistant and the team loses the repeatability that a coding agent is supposed to improve.

A balanced setup often works best: one stable cloud model for hard repository edits, one local Ollama model for low-risk questions or private experiments, and a short note explaining when to use each.