OpenCode with Local AI (Ollama) Setup Guide

A quick yet comprehensive step-by-step guide to install and configure OpenCode to use local AI models via Ollama.

Quick Start (TL;DR)

# 1. Install OpenCode
npm install -g opencode

# 2. Install Ollama and pull models
ollama pull mistral:7b

# 3. Create config file
mkdir -p ~/.config/opencode
cat > ~/.config/opencode/opencode.json << 'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "mistral:7b": {
          "name": "mistral:7b"
        }
      }
    }
  }
}
EOF

# 4. Start Ollama
ollama serve &

# 5. Start OpenCode
opencode

---

Last Updated: December 2025

Table of Contents

• Prerequisites
• Installation
• Ollama Setup
• OpenCode Configuration
• Troubleshooting

---

Prerequisites

• Node.js 18+ or npm installed
• Ollama installed and running (see Ollama Setup)
• Git (optional, for cloning)
• Terminal/CLI access

---

Installation

1. Install OpenCode

# Using npm (recommended)
npm install -g opencode

# Verify installation
opencode --version

2. Verify Installation

# Start OpenCode
opencode

You should see the OpenCode CLI interface. Press Ctrl+C to exit.

---

Ollama Setup

1. Install Ollama

Download from ollama.ai for your operating system (macOS, Linux, Windows).

2. Start Ollama Server

# On Linux/macOS
ollama serve

# On Windows
# Ollama runs as a service automatically after installation

Default: Ollama listens on http://localhost:11434

3. Pull Models

# Pull a model (example: Mistral 7B)
ollama pull mistral:7b

# Pull multiple models
ollama pull llama3.1:8b
ollama pull gpt-oss:20b
ollama pull deepseek-r1:14b

# View installed models
ollama list

4. Verify Ollama is Running

# Test API connectivity
curl http://localhost:11434/api/tags

# Should return JSON with your models

---

OpenCode Configuration

1. Create Configuration Directory

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

2. Create opencode.json

Create file at ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "mistral:7b": {
          "name": "mistral:7b"
        },
        "llama3.1:8b": {
          "name": "llama3.1:8b"
        },
        "gpt-oss:20b": {
          "name": "gpt-oss:20b"
        }
      }
    }
  }
}

Important: Replace model names with ones from your ollama list output.

3. Configure Remote Ollama (Optional)

If Ollama runs on a different machine:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (remote)",
      "options": {
        "baseURL": "http://10.1.20.142:11434/v1"
      },
      "models": {
        "gpt-oss:20b": {
          "name": "gpt-oss:20b"
        }
      }
    }
  }
}

Replace 10.1.20.142 with your Ollama server's IP address.

4. Add All Your Models

# Get exact model names
ollama list

Add each model to the models object in your config:

"models": {
  "model-name:size": {
    "name": "model-name:size"
  }
}

Critical: The key and name value must match exactly what ollama list shows.

5. Restart OpenCode

opencode

6. Verify Configuration

Inside OpenCode, run:

/models

Your Ollama models should appear in the list.

---

Configuration Examples

Minimal Setup (Single Model)

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

Full Setup (Multiple Models)

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "gpt-oss:20b": {
          "name": "gpt-oss:20b"
        },
        "llama3.1:8b": {
          "name": "llama3.1:8b"
        },
        "deepseek-r1:14b": {
          "name": "deepseek-r1:14b"
        },
        "deepseek-v2:16b": {
          "name": "deepseek-v2:16b"
        },
        "deepseek-r1:32b": {
          "name": "deepseek-r1:32b"
        },
        "gemma3:27b": {
          "name": "gemma3:27b"
        },
        "llava:7b": {
          "name": "llava:7b"
        },
        "qwen2.5:32b": {
          "name": "qwen2.5:32b"
        },
        "llama2:13b": {
          "name": "llama2:13b"
        },
        "mistral:7b": {
          "name": "mistral:7b"
        },
        "gemma2:27b": {
          "name": "gemma2:27b"
        },
        "phi3:14b": {
          "name": "phi3:14b"
        }
      }
    }
  }
}

---

Troubleshooting

Issue: "Model 'X' not found"

Cause: Model name in config doesn't match Ollama's model name.

Solution:

# Get exact names
ollama list

# Update opencode.json with exact names (including colons and sizes)
# Example: "mistral:7b" not "mistral-7b"

Issue: OpenCode shows only "Ollama Cloud"

Cause: Configuration file not found or not loaded.

Solution:

# Verify config file location
ls -la ~/.config/opencode/opencode.json

# Verify JSON syntax
cat ~/.config/opencode/opencode.json | jq .

# Check if models section exists in config

Issue: "Connection refused" or "Cannot reach Ollama"

Cause: Ollama not running or wrong address.

Solution:

# Verify Ollama is running
ollama ps

# Test API connectivity
curl http://localhost:11434/api/tags

# For remote Ollama, verify network connectivity
curl http://<OLLAMA_IP>:11434/api/tags

Issue: Configuration not reloading

Solution:

# Clear OpenCode cache
rm -rf ~/.local/share/opencode/auth.json

# Restart OpenCode
opencode

---

Common Commands

# List all models in OpenCode
/models

# Set default model
/model <model-name>

# View configuration
/config

# Export session
/export

# Create new session
/session new

---

Performance Tips

• Use smaller models (7B-13B) for faster responses
• GPU acceleration: Ensure Ollama uses GPU (check ollama ps)
• Context window: Larger models support longer context (see model docs)
• Temperature: Adjust for creativity vs. consistency in prompts

---

Resources

• OpenCode Docs
• Ollama Documentation
• Available Models
• OpenCode GitHub

---