How to Use OpenCode with Ollama: Local AI Coding Agent Setup

What is OpenCode — and Why It Matters

OpenCode is an open-source, terminal-based AI coding agent — think Claude Code or GitHub Copilot Chat, but fully provider-agnostic and free. It runs in your terminal as a TUI (terminal user interface) and can browse your codebase, edit files, run shell commands, and reason about multi-file architecture.

Unlike proprietary tools, OpenCode lets you connect to any LLM provider — Anthropic, OpenAI, Google, or a completely local model via Ollama. When you pair it with Ollama, your code never leaves your machine. No cloud, no telemetry, no usage limits.

Prerequisites & System Requirements

Before starting, make sure your machine meets the minimum requirements. Running local LLMs is GPU-bound — the more VRAM or unified memory you have, the larger and better the model you can run.

Step 1 — Install Ollama and Pull a Model

Ollama is a local LLM runtime that manages model downloads and exposes an OpenAI-compatible API on localhost:11434. OpenCode communicates with it via the /v1 endpoint.

# macOS (Homebrew)
brew install ollama
 
# Linux (one-liner)
curl -fsSL https://ollama.com/install.sh | sh
 
# Verify install
ollama --version
 
# Start the server (keep this running in a terminal tab)
ollama serve

Now pull a coding-optimised model. For most machines, qwen2.5-coder:7b is the best starting point. If you have 16GB+ VRAM or unified memory, go for the 32B variant.

# Best balance of quality + speed (8B params, ~5GB)
ollama pull qwen2.5-coder:7b
 
# Larger, more capable (requires 16GB+ VRAM)
ollama pull qwen3-coder:30b
 
# Fastest option for low-spec machines
ollama pull deepseek-coder:6.7b
 
# Verify models are ready
ollama list

Step 2 — Fix the Context Window (Critical)

This is the step most tutorials skip — and the reason tool calls silently fail. Ollama defaults all models to a 4,096-token context window, even when the model supports 128k+. OpenCode needs at least 16k tokens to use agentic tools like file editing and bash execution.

# Open the model in an interactive session
ollama run qwen2.5-coder:7b
 
# Inside the Ollama prompt, set context length
>>> /set parameter num_ctx 16384
 
# Save as a new named variant
>>> /save qwen2.5-coder:7b-16k
 
# Exit
>>> /bye
 
# For larger RAM machines — 32k context (better results)
ollama run qwen2.5-coder:7b
>>> /set parameter num_ctx 32768
>>> /save qwen2.5-coder:7b-32k
>>> /bye

Alternatively, if you run Ollama as a systemd service you can set the context globally via an environment variable:

# /etc/systemd/system/ollama.service (add to [Service] block)
Environment="OLLAMA_CONTEXT_LENGTH=32000"

Step 3 — Install OpenCode

OpenCode is distributed as an npm package. Install it globally so you can run opencode from any directory.

# Install via npm (Node.js 18+ required)
npm install -g opencode-ai
 
# Verify install
opencode --version
 
# If npm global bin isn't in PATH, add it:
export PATH="$PATH:$(npm root -g)/../bin"
 
# Initialise in your project directory
cd ~/your-project
opencode init

Running opencode init creates an agents.mmd file that maps your project structure — this is how OpenCode understands your codebase before you write a single prompt.

Step 4 — Configure opencode.json for Ollama

OpenCode reads provider configuration from ~/.config/opencode/opencode.json. Create or edit this file to point at your local Ollama server. The key detail: OpenCode uses the /v1 OpenAI-compatible endpoint — not Ollama's native API.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ollama/qwen2.5-coder:7b-16k",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (Local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen2.5-coder:7b-16k": {
          "name": "Qwen2.5 Coder 7B (16k)",
          "tools": true
        }
      }
    }
  }
}

Want to configure multiple models and switch between them? Here's a multi-model config:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ollama/qwen2.5-coder:7b-16k",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (Local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen2.5-coder:7b-16k": {
          "name": "Qwen2.5 Coder 7B — Fast",
          "tools": true
        },
        "qwen3-coder:30b-32k": {
          "name": "Qwen3 Coder 30B — Powerful",
          "tools": true
        },
        "deepseek-coder:6.7b-16k": {
          "name": "DeepSeek Coder 6.7B — Lightweight",
          "tools": true
        }
      }
    }
  }
}

Step 5 — Run OpenCode and Start Coding

With Ollama running and the config in place, launch OpenCode from inside your project directory:

# Make sure Ollama is still running in another terminal
ollama serve
 
# Navigate to your project, then start OpenCode
cd ~/your-project
opencode
 
# Or run a one-shot task non-interactively
opencode run "add TypeScript types to all functions in src/api.js" \
  --model ollama/qwen2.5-coder:7b-16k

Once inside the TUI, here are the key commands to know:

Best Ollama Models for OpenCode in 2026

Not all Ollama models support agentic tool use. Only models specifically trained for function calling and tool execution work correctly with OpenCode's file and bash operations. Here's the current best options ranked by use case:

Troubleshooting Common Issues

Frequently Asked Questions

Related Reading

• Local AI Agent with Python, Ollama & LangChain RAG
• OpenRouter API + Next.js Tutorial 2026
• Claude Code vs GitHub Copilot
• OpenClaw vs n8n: AI Automation Comparison
• OpenClaw WhatsApp Automation Guide 2026
• OpenClaw + Claude Code Setup Guide
• OpenClaw Browser Extension Install
• Run OpenClaw on a VPS
• Fix OpenClaw Disconnected 1008 Error
• Best AI Interview Platforms 2026
• Best AI Interview Platform for Candidates
• How to Practice STAR Method for Amazon Interviews with AI
• Best AI Resume Builders in the USA
• How to Optimize Your Resume for Remote Jobs with AI
• Should I Opt Out of AI Resume Screening?