Improve documentation for self-hosted LLMs

Unclear how to configure opencode when using a self-hosted (through LiteLLM Proxy for example) OpenAI-compatible provider.

We have this currently, https://opencode.ai/docs/models/#local

What else would you want to see here?

Sorry, it wasn't totally clear to me where to put things initially. Perhaps a more flushed out config such as:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "litellm": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://your.url.here/v1",
        "apiKey": "YourKeyHere"
      },
      "models": {
        "gpt-4o": {
          "name": "GPT-4o",
          "attachment": true,
          "reasoning": false,
          "temperature": true,
          "tool_call": true,
          "cost": {
            "input": 0.0025,
            "output": 0.01
          },
          "limit": {
            "context": 128000,
            "output": 4096
          }
        },
        "gpt-4o-mini": {
          "name": "GPT-4o Mini",
          "attachment": true,
          "reasoning": false,
          "temperature": true,
          "tool_call": true,
          "cost": {
            "input": 0.00015,
            "output": 0.0006
          },
          "limit": {
            "context": 128000,
            "output": 16384
          }
        },
        "claude-3-5-sonnet-20241022": {
          "name": "Claude 3.5 Sonnet",
          "attachment": true,
          "reasoning": false,
          "temperature": true,
          "tool_call": true,
          "cost": {
            "input": 0.003,
            "output": 0.015
          },
          "limit": {
            "context": 200000,
            "output": 8192
          }
        }
      }
    }
  },
  "model": "litellm/gpt-4o",
  "autoshare": false,
  "autoupdate": true,
  "theme": "default"
}

I'm lost at how to use a local model as well. I'm running models via Ollama. I've read through all of the documentation. I attempted to copy the config above into /Users/myuser/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://localhost:11434"
      },
      "models": {
        "gemma3:4b": {
          "name": "Gemma 3 4B",
          "attachment": true,
          "reasoning": false,
          "temperature": true,
          "tool_call": false,
          "cost": {
            "input": 0,
            "output": 0
          },
          "limit": {
            "context": 8192,
            "output": 2048
          }
        }
      }
    }
  },
  "model": "ollama/gemma3:4b",
  "autoshare": false,
  "autoupdate": true,
  "theme": "default"
}

The error I get when I try opencode run

ERROR 2025-07-07T17:28:46 +2ms service=default name=Error message=no providers found fatal

When I try opencode models, the list is blank.

I've installed @ai-sdk/openai-compatible globally using npm.

There is no information on auth for local models. My Ollama server doesn't require auth.

For Ollama models simply add an apiKey field and it works. For example this complete config works:

 {
  "$schema": "https://opencode.ai/config.json",
  "theme": "opencode",
  "autoshare": false,
  "autoupdate": true,
  "model": "ollama/starcoder",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1",
        "apiKey": "AnythingHere"
      },
      "models": {
        "qwen3:14b": {
          "name": "Qwen3 14B"
        }
      }
    }
  }
}

@rnusser

Thanks, I got it working with a config similar to what @rnusser shared.
My issue was that I used the wrong name for my global config file
/Users/myuser/.config/opencode/opencode.json should have been /Users/myuser/.config/opencode/config.json

This confusion was due to the documentation for models showing the file name of a local config opencode.json rather than the global config file name which is explained in the config section of the documentation.

I cannot - for the life of mine - configure the Ollama provider.
I've placed the config.json into ~/.config/opencode/config.json:

{
  "$schema": "https://opencode.ai/config.json",
  "autoshare": false,
  "autoupdate": true,
  "theme": "default",
  "model": "ollama/qwen2.5-coder",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama @ Radon",
      "options": {
        "baseURL": "http://192.168.1.157:11434/v1",
        "apiKey": "ollama"
      },
      "models": {
        "qwen2.5-coder": {
          "name": "qwen2.5 coder"
        },
        "gemma3": {
          "name": "gemma3"
        },
        "codellama": {
          "name": "codellama"
        }
      }
    }
  }
}

And opencode doesn't pick that up. It doesn't even change the theme, like opencode was never reading this file at all.

I'm on the v0.0.55 - am I missing something here?

Same same but different. I can't figure out Cerebras. I think it is related. #976

@marad

@marad ~/.config/opencode/opencode.json maybe? At least that is what the docs say .

In my case, I get an error of Error: Was there a typo in the url or port? but the URL is correct for Ollama server.

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

What is interesting if I use http://localhost:11434/v1 as URL it works well, it also works with LM Studio. The network settings are OK because I can curl the server and I get the models back.

Any hints on this one, is this a bug in opencode ?

Merge pull request anomalyco#665 from ymdvsymd/fix/worktree-project-i…

Navigation Menu

Repository navigation

Improve documentation for self-hosted LLMs #665

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Improve documentation for self-hosted LLMs #665

Description

Activity

jayair commented on Jul 3, 2025

dcieslak19973 commented on Jul 3, 2025

StevenUS commented on Jul 7, 2025

rnusser commented on Jul 8, 2025

StevenUS commented on Jul 8, 2025

marad commented on Jul 10, 2025

deadcoder0904 commented on Jul 14, 2025

madflow commented on Jul 18, 2025

gergob commented on Nov 27, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions