OpenCode Ollama Setup: Run a Local Coding Agent Step by Step

Quick start: launch OpenCode through Ollama

Confirm that both applications are installed and that ollama list works. In a terminal, change into the repository you want OpenCode to see. Run ollama launch opencode and choose a suitable local or cloud model.

The launcher is the best first attempt because Ollama documents it as the direct integration path. It pulls a required model when needed, configures the integration, prepares a 64K context setting for coding work, and launches OpenCode.

What each layer does before you configure it

OpenCode is the coding agent and terminal interface. Ollama is the model runtime or cloud-model gateway. Your repository remains a separate trust boundary: the model can propose changes, but OpenCode permissions determine whether commands and edits can run.

Start inside a small test repository. Keep Git clean, create a backup or branch, and avoid granting broad shell access until read-only inspection and a simple patch work correctly.

What ollama launch changes for OpenCode

The interactive ollama launch menu lists supported coding integrations and their suggested models. Selecting OpenCode prepares the connection so the interface can send repository context and prompts to an Ollama-backed model.

A successful launch does not prove that every model fits your machine. Local inference consumes RAM or VRAM and context cache; cloud models reduce local hardware pressure but require internet access and send prompts to the selected remote service.

Manual opencode.json configuration

Use manual configuration when the launcher cannot find your model, you need a non-default endpoint, or you want the provider definition committed as a reviewed project setting. OpenCode documents an Ollama provider using the OpenAI-compatible adapter and the local v1 endpoint.

Replace the example model ID with a model already shown by ollama list. Keep the model identifier identical in the provider model key and name so selection is predictable.

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

Set enough context for repository work

OpenCode documentation warns that a small Ollama context window can produce poor tool behavior or out-of-memory errors. Ollama recommends at least 64K tokens for coding tools and agents.

The launcher handles this automatically for supported integrations. For a manual model, create a Modelfile with a larger num_ctx value, build a named variant, and reference that variant in OpenCode. Reduce context only when your hardware cannot sustain it, then limit the files and task scope.

FROM your-model
PARAMETER num_ctx 65536

Choose a model by workload, not by leaderboard

The correct model is the one that stays responsive after the editor, repository index, terminal, tests, and context cache are loaded. Begin with a smaller coding-capable model, test a real patch, and move upward only when quality gains justify slower responses or memory pressure.

Cloud models available through Ollama can handle larger tasks without consuming local model memory, but they change the privacy and connectivity tradeoff. Treat the choice as a deployment decision, not only a benchmark score.

Troubleshoot the connection in the right order

If OpenCode shows no Ollama models, first confirm that the Ollama service is running and ollama list returns the expected model. Then verify that the manual base URL is http://localhost:11434/v1 and that the model key exactly matches the installed tag.

If responses stop during repository analysis, reduce the selected files, close memory-heavy applications, or test a smaller model. If tool calls are malformed, increase context and use a model suited to coding-agent workflows. If commands fail, inspect OpenCode permissions and the working directory rather than changing the endpoint.

Use a safe first coding task

Ask OpenCode to explain the repository and propose a plan before allowing edits. Review the file list, then permit one bounded change and run a specific test. Inspect git diff before accepting more work.

Do not expose the Ollama endpoint publicly without authentication and network controls. Do not paste secrets into prompts. Local inference improves data control, but the agent can still read files and run commands that its interface is allowed to access.