Run OpenCode with a model you host yourself

The OpenCode local model setup is one provider entry in opencode.jsonc that points at an OpenAI-compatible server, and on a rented GPU that server sits behind an SSH tunnel, so its URL on your machine is http://127.0.0.1:8000/v1. Three details decide whether the result works as a coding agent: the server needs tool calling switched on, the provider entry has to say so because OpenCode does not detect it for vLLM, and the context limit in the entry has to match the server's. I followed the OpenCode v2 documentation, which opencode.ai names as the current version, and checked everything below on 12 November 2026.

What OpenCode needs from the server

OpenCode is an open source coding agent that runs on your machine and calls a model over HTTP, so with a model on your own server it is a self-hosted coding agent. Its providers page says to use the compatible runtime for any API that implements the OpenAI request format, and its models page lists built-in discovery for Ollama, LM Studio and vLLM at their default local addresses, ports 11434, 1234 and 8000. A tunnel puts the VM's port on your own 127.0.0.1, so discovery sees a rented server as a local one. The model has to support tool calls, because an agent edits files through tools, and Ollama's OpenCode page says OpenCode requires a context length of 64k or higher.

The config shape changed between major versions. The migration guide says OpenCode 2 still reads the OpenCode 1 shape (provider, npm, options) from the same locations, and Ollama's page still shows that older shape. I write the native v2 shape (providers, package, settings) that the OpenCode docs show today.

Install OpenCode on your own machine

Install it where your code is, not on the VM:

curl -fsSL https://opencode.ai/v2/install | bash

The intro page also lists npm install -g @opencode/cli and brew install anomalyco/tap/opencode-v2. The migration guide says OpenCode 1 and 2 both use the opencode command and the curl installer replaces the old binary, so remove a package-managed OpenCode 1 first. The newest OpenCode 2 release on GitHub, v2.2.7, is from 10 November 2026, and the repository is MIT licensed.

OpenCode with vLLM: serve the model and open the tunnel

Launch a plain GPU VM with an 80 GB GPU and run nvidia-smi. vLLM's latest image is built for CUDA 13 and needs a driver of 580 or newer, as the Claude Code guide explains, and the vLLM guide covers the loopback binding and the memory flags.

The server command is the one from the Claude Code guide, because both tools need tool calls, a served name without a slash and a long context:

sudo docker run -d --name vllm --gpus all --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen3-Coder-30B-A3B-Instruct-FP8 \
  --served-model-name coder \
  --max-model-len 131072 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_xml

Open the tunnel from your own machine, with the user, host and port from the SSH command on your deployment, and read the model list. The port forwarding guide has the SSH user for each provider:

ssh -N -L 8000:127.0.0.1:8000 ubuntu@YOUR_VM_IP -p 22
curl http://localhost:8000/v1/models

The reply carries max_model_len, the number OpenCode's discovery reads as the context limit.

Define the provider in opencode.jsonc

Discovery would list the vLLM model, but the models page says discovered vLLM models advertise text input and output and not tools, because the tool flags are server settings that discovery cannot read. For a coding agent that is not enough, so I define the provider myself, which is the recipe the docs give for another OpenAI-compatible server. Put this in opencode.jsonc in your project, or in ~/.config/opencode/opencode.json for every project:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "gpu/qwen3-coder",
  "providers": {
    "gpu": {
      "name": "Rented GPU",
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "http://127.0.0.1:8000/v1"
      },
      "models": {
        "qwen3-coder": {
          "name": "Qwen3-Coder 30B-A3B FP8",
          "modelID": "coder",
          "capabilities": {
            "tools": true,
            "input": ["text"],
            "output": ["text"]
          },
          "limit": {
            "context": 131072,
            "output": 16384
          }
        }
      }
    }
  }
}

The provider ID gpu and the model key qwen3-coder make the reference gpu/qwen3-coder. The modelID is the name sent to the server, which is the --served-model-name. The capabilities.tools line tells OpenCode to send tool definitions, and limit sets the window and the output size. The models page says OpenCode cannot detect whether such values are accurate, so they must match the server. If you start vLLM with --api-key, add "apiKey": "{env:VLLM_API_KEY}" to settings, the substitution form the docs use.

Start OpenCode in a project folder and run /models to confirm that gpu/qwen3-coder is listed. One command exercises the whole path, because listing a folder takes a tool call:

opencode run --model gpu/qwen3-coder "List the files in this folder"

Tool calling is a server setting

A server started without these settings still answers chat requests, so the failure looks like a model that talks about editing a file instead of editing it. Check the server flags first and the capabilities.tools line second.

Context settings that matter for an agent

Three numbers have to agree. vLLM's --max-model-len counts prompt and output together, limit.context tells OpenCode the window and limit.output is how much of it one reply may take. I use 131072 and 16384. OpenCode's compaction page says automatic compaction is on by default and keeps 15,000 tokens of recent conversation beside a summary. Its buffer setting is the share of the window kept free, 15% by default and at least 16k, so on a 131,072-token window compaction starts at about 111,000 tokens (calculated).

A model told that its window is larger than the server's keeps sending prompts the server rejects. The compaction page says a request rejected as too long is compacted and retried once, and a second rejection is returned as an error. OpenCode also runs subagents against the same server, so leave room for more than one session. The Claude Code guide has the memory table for this model: about 12.9 GB of KV cache per 131,072-token session, which an 80 GB card with the FP8 build holds about three times (calculated).

OpenCode with Ollama on the VM

Install Ollama on the VM and set OLLAMA_CONTEXT_LENGTH=131072, exactly as the Ollama section of the Claude Code guide shows, then pull the model:

ollama pull qwen3-coder:30b

Open a tunnel to port 11434 from your own machine:

ssh -N -L 11434:127.0.0.1:11434 ubuntu@YOUR_VM_IP -p 22

OpenCode probes http://127.0.0.1:11434, reads the context and tool-use capabilities from Ollama and lists the model in /models as ollama/qwen3-coder:30b, with no provider entry. If Ollama already runs on your own machine, forward to another local port, say 11435, and set the URL. The docs say discovery then uses the same path prefix:

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "ollama": {
      "settings": {
        "baseURL": "http://127.0.0.1:11435/v1"
      }
    }
  }
}

Ollama's page also offers ollama launch opencode, and its manual setup still shows the OpenCode 1 config shape. The Open WebUI and Ollama template does not expose Ollama's API, so this variant needs a plain GPU VM too, and the Ollama guide covers the install.

llama.cpp as the server

For llama.cpp, use the custom provider above with the tunnel's port. Start llama-server with --jinja, an --alias that matches modelID, a -c equal to limit.context and an explicit --port. The llama.cpp server guide has the container command and the flags for fitting a quantized file to the card.

Choose a model for OpenCode

I do not name a best model for OpenCode here. A model has to meet three requirements: the server has a tool parser or template for it, the context is at least 64k with an accurate limit.context, and the GPU holds the weights plus the KV cache. The open coding models page lists candidates with the GPU each needs, and the Qwen3-Coder page covers the 30B-A3B used here and its larger sibling.

When it does not work