Local AI Coding Setup: Ollama + OpenCode on macOS Terminal

How to Connect OpenCode to Ollama: Local AI Coding Setup

Updated July 2026: added Docker setup, the exact error messages decoded, and the OLLAMA_CONTEXT_LENGTH alternative for num_ctx.

Want a fully local AI coding agent running in your terminal with zero cloud dependencies? This guide walks you through setting up Ollama (local LLM runner) and OpenCode (open-source AI coding agent) on macOS with Apple Silicon. The result: agentic coding capabilities, tool use, multi-model support, all running on your machine. You will find the complete working opencode.json below, ready to copy and paste.

MLX-CODE vs Ollama + OpenCode

If you read our MLX-CODE article, you might wonder how this setup compares. Here's a quick breakdown:

Both approaches are valid. MLX-CODE is lighter and more self-contained; Ollama + OpenCode is more feature-rich for agentic coding workflows.

System Requirements

On Linux the same setup works with curl -fsSL https://ollama.com/install.sh | sh instead of Homebrew: the OpenCode config in Step 7 is identical.

Step 1. Install Ollama

Ollama is a local LLM runner that manages model downloads, serves an OpenAI-compatible API, and handles GPU acceleration automatically.

# Install via Homebrew
brew install ollama

# Verify installation
ollama --version

# Start the server (keep running in a terminal tab)
ollama serve

Keep ollama serve running, OpenCode connects to it via the local API.

Step 2. Download Coding Models

Pull one or more models optimized for code generation:

# Recommended, best quality/speed balance
ollama pull qwen2.5-coder:7b

# Alternatives
ollama pull deepseek-coder:6.7b
ollama pull codellama:7b

# List installed models
ollama list

# Remove a model
ollama rm model-name

Step 3. Verify the Ollama API

Ollama exposes two endpoints. OpenCode uses the OpenAI-compatible one:

# Check Ollama native API
curl http://localhost:11434/api/tags

# Check OpenAI-compatible endpoint (used by OpenCode)
curl http://localhost:11434/v1/models

Step 4. Configure Model Context Window

Ollama defaults to a 4K context window, which is too small for agentic coding. You need at least 16K:

# Create a 16K context variant
ollama run qwen2.5-coder:7b
/set parameter num_ctx 16384
/save qwen2.5-coder:7b-16k
/bye

# For even better results (if you have 16GB+ RAM)
ollama run qwen2.5-coder:7b
/set parameter num_ctx 32768
/save qwen2.5-coder:7b-32k
/bye

This creates new model variants with the increased context. Use these names in your OpenCode config.

# Set the default context window for every model (Ollama 0.5.13+)
launchctl setenv OLLAMA_CONTEXT_LENGTH 16384   # macOS app
OLLAMA_CONTEXT_LENGTH=16384 ollama serve       # manual serve

Step 5. Test the Model

# Interactive chat to verify it works
ollama run qwen2.5-coder:7b-16k

# Try a coding prompt
> write a debounce function in typescript

# Exit
/bye

Step 6. Install OpenCode

OpenCode is an open-source AI coding agent with a terminal TUI, plan/build modes, tool use, and undo/redo. Install globally via npm:

# Install globally
npm install -g opencode-ai

# Verify
opencode --help

Other install methods: Homebrew (brew install opencode), Bun, pnpm, Yarn, or Docker.

Step 7. Connect OpenCode to Ollama

Create the configuration file to connect OpenCode to your local Ollama instance:

# Create config directory
mkdir -p ~/.config/opencode

# Create config file
nano ~/.config/opencode/opencode.json

Paste this configuration:

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

Step 8. Use OpenCode

Navigate to any project and launch:

cd /path/to/your/project
opencode .

OpenCode Key Features

• Plan Mode

  Press Tab to toggle. Generates implementation strategies without modifying code. Great for reasoning through complex tasks first.

• Build Mode

  The default mode. OpenCode reads, writes, and modifies files in your project with tool use capabilities.

• Undo / Redo

  Use /undo and /redo to revert or restore changes. Safe experimentation.

• File References

  Press @ to fuzzy-search and attach project files to your prompt. Context-aware conversations.

• AGENTS.md

  Run /init to generate an AGENTS.md file. OpenCode learns your project patterns and conventions.

• Share Conversations

  Use /share to create a shareable link of your conversation for team collaboration.

Multi-Model Configuration

Add multiple models and switch between them with Ctrl+A:

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

The small_model is used for lightweight tasks like generating titles or summaries.

Recommended Models by Task

Remember to create 16K+ context variants for each model you use with agentic workflows.

Running Ollama in Docker

Prefer containers? Ollama ships an official image, and OpenCode connects to it with the exact same config, since the port mapping keeps the endpoint at localhost:11434:

# Start Ollama in Docker (CPU)
docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

# Pull a model inside the container
docker exec -it ollama ollama pull qwen2.5-coder:7b

# Linux with NVIDIA GPU: add --gpus=all (requires nvidia-container-toolkit)
docker run -d --gpus=all -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

Troubleshooting: the exact errors, decoded

Quick Reference Commands

# Ollama
ollama serve                          # Start server
ollama list                           # List models
ollama pull qwen2.5-coder:7b          # Download model
ollama rm model-name                  # Remove model
curl http://localhost:11434/api/tags   # Check status
curl http://localhost:11434/v1/models  # OpenAI-compatible check

# OpenCode
opencode .                            # Launch in current project
/init                                 # Generate AGENTS.md
/undo                                 # Undo last change
/redo                                 # Redo last change
/share                                # Share conversation
/help                                 # List all commands
Tab                                   # Toggle plan/build mode
Ctrl+A                                # Switch models
@                                     # Fuzzy-search project files

Conclusion

With Ollama and OpenCode you get a fully local, privacy-first AI coding agent with agentic capabilities that rival cloud-based tools. No API keys, no subscriptions, no data leaving your machine. Curious what the same workload would cost on cloud APIs? Plug your token volume into our LLM Cost Calculator to compare Claude, GPT, Gemini and DeepSeek pricing, or estimate prompt sizes with the AI Token Counter.

If you're already using MLX-CODE for quick local inference, consider adding Ollama + OpenCode to your toolkit for more complex agentic workflows. Both tools complement each other: MLX-CODE for lightweight, GPU-native inference and OpenCode for full-featured coding agent capabilities.

Resources

• OpenCode Documentation

  Official docs for installation, configuration, providers, and commands.

• Ollama Documentation

  Model library, API reference, and advanced configuration.

• Ollama x OpenCode Guide

  Community guide for connecting Ollama with OpenCode.

• AI Terminal Coding (GitHub)

  Full setup instructions and configuration files for the Ollama + OpenCode workflow covered in this article.

• MLX-Terminal-Code (GitHub)

  Source code and setup for MLX-CODE, the local AI coding assistant covered in our previous article.

• MLX-CODE on CodeHelper

  Our previous article on local AI coding with Apple's MLX framework.