DEV Community

Cover image for OpenCode Ollama Setup: Run a Local AI Coding Agent
KAMAL KISHOR
KAMAL KISHOR

Posted on

OpenCode Ollama Setup: Run a Local AI Coding Agent

#ai #coding #llm #tutorial

Dealing with repetitive coding tasks or needing quick code explanations often means relying on cloud-based AI assistants. This can introduce concerns about data privacy, offline availability, or recurring subscription costs. Fortunately, there are robust local alternatives emerging.

Like many developers, I often prefer free, local AI tools over paid subscriptions when the quality is good enough. I even wrote about replacing Cursor with a free local AI coding assistant, and OpenCode with Ollama takes this further, providing a powerful, privacy-focused coding agent that runs directly on your machine.

Getting Started

You're going to set up OpenCode, an open-source AI coding agent, to work with Ollama, which allows you to run large language models (LLMs) locally. This combination gives you an AI assistant right in your terminal, capable of understanding your codebase, suggesting changes, and executing commands, all without sending your code to external servers.

Here's what you need before you start:

  • Ollama Installed: Download and install Ollama from ollama.ai for your operating system.
  • An Ollama Model: You'll need to pull at least one suitable LLM using Ollama, such as qwen3.5 or gpt-oss. These models are often better for code-related tasks.
  • Node.js (v18.0.0 or higher): OpenCode is often distributed as a Node.js CLI tool.
  • A Modern Terminal Emulator: While OpenCode runs in any standard terminal, a GPU-accelerated emulator like WezTerm, Alacritty, Ghostty, or Kitty offers a smoother experience.
  • Windows Subsystem for Linux (WSL): If you're on Windows, using WSL is highly recommended for better performance and full compatibility with OpenCode's features.

Setting Up OpenCode with Ollama

First, ensure Ollama is installed and you've pulled a model. For example, to pull the qwen3.5 model:

ollama pull qwen3.5
Enter fullscreen mode Exit fullscreen mode

Next, install OpenCode. The easiest way for macOS and Linux is using the install script.

curl -fsSL https://opencode.ai/install | bash
Enter fullscreen mode Exit fullscreen mode

Alternatively, you can install it globally via npm:

npm install -g opencode-ai
Enter fullscreen mode Exit fullscreen mode

Verify the installation by checking the version:

opencode --version
Enter fullscreen mode Exit fullscreen mode

Now, let's configure OpenCode to use your local Ollama models. While ollama launch opencode can automatically set up a basic connection, for more control, you can configure it manually.

Run opencode init to create a default configuration file, typically located at ~/.config/opencode/opencode.json.
Then, edit this file to include Ollama as a provider. Here’s an example opencode.json snippet:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3.5": { "name": "qwen3.5" }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Important: A common pitfall with Ollama models and OpenCode is the context window size. OpenCode often expects a larger context (e.g., 64K-128K tokens) for effective tool calling, while Ollama models might default to smaller sizes like 4K or 16K. This mismatch can lead to unexpected behavior or incomplete responses. To address this, set the OLLAMA_CONTEXT_LENGTH environment variable before starting your Ollama server or launching OpenCode:

export OLLAMA_CONTEXT_LENGTH=65536
Enter fullscreen mode Exit fullscreen mode

Then, start Ollama and launch OpenCode from your project directory:

opencode
Enter fullscreen mode Exit fullscreen mode

Inside OpenCode's terminal user interface (TUI), you can use the /models command to select your configured Ollama model.

Quick Example and Common Problems

Once OpenCode is running, navigate to a project directory in your terminal and type opencode. You can then interact with it directly. For a quick test, try:

Create a file named hello.txt and write "OpenCode was here".
Enter fullscreen mode Exit fullscreen mode

OpenCode will plan, ask for your approval, and then execute the action, creating the hello.txt file in your current directory.

Common issues often revolve around the context window and model capabilities. If OpenCode hangs or returns truncated responses, it's frequently due to the context window mismatch discussed above. Ensure you've set OLLAMA_CONTEXT_LENGTH to a sufficiently large value (e.g., 65536 or higher, if your model supports it) before starting Ollama.

Another problem is that smaller local models (under ~27B parameters) might struggle with effective tool calling and complex agentic tasks. If OpenCode's file operations or commands aren't executing as expected, consider pulling a larger, more capable model like qwen3.6:27b or gpt-oss:20b for reliable tool use. Also, ensure your system has adequate RAM and VRAM; local LLMs are resource-intensive, and insufficient hardware can lead to very slow responses or crashes. If OpenCode can't connect to Ollama, verify that the Ollama server is running and accessible at http://localhost:11434/v1. You might also need to clear OpenCode's provider package cache using rm -rf ~/.cache/opencode (or delete %USERPROFILE%\.cache\opencode on Windows) and restart OpenCode.

While running AI agents locally offers privacy and control, it's important to recognize that even with a good setup, local models can sometimes lag behind frontier cloud models in terms of raw capability and speed for highly complex tasks. This is especially true for tasks that require massive context windows or intricate reasoning.

Sources

This article was generated with AI (Google Gemini + web search). Please check important details against the sources above.

Daily AI notes on LinkedIn — Kamal Kishor

Top comments (0)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.