# OpenCode custom provider: local model configuration in V2

Configure an OpenCode V2 custom local provider with the correct package, endpoint, model entry, and explicit provider/model selection.

Author: Retrivium team
Updated: 2026-11-03
Canonical URL: https://retrivium.ai/journal/opencode-v2-custom-local-provider/
Language: en

Configure a custom local provider in OpenCode V2 using the V2 providers shape, then select its provider/model reference. Older singular provider examples are not a safe substitute for the current generation’s documented configuration.

## The concrete application boundary

A minimal V2 custom provider has several fields with different purposes. The key under providers is the provider ID used in references. The name field is a display label. The package chooses the implementation, and settings.baseURL supplies the endpoint for the compatible package. Model entries under models identify what the application can select. The official example uses @opencode/ai/providers/openai-compatible; settings are package-specific, so copying a field from an unrelated package may have no effect. This distinction is especially important when moving from V1 tutorials. Keep a separate note of the installed OpenCode generation before changing configuration, because both generations use the default executable name opencode. Use a read-only prompt with pasted source text for the initial trial, then introduce repository tools as a separate step. A successful model selector entry does not establish that those tools are permitted ([OpenCode V2 introduction](https://opencode.ai/v2/docs/)).

## A practical route

In opencode.jsonc define providers with a local provider ID. Use package @opencode/ai/providers/openai-compatible, put the existing local endpoint in settings.baseURL, and add the actual model ID under models. The selected reference combines the provider ID and model ID. Open /models to choose it, then ask a read-only question before attempting file actions ([OpenCode V2 Providers](https://opencode.ai/v2/docs/providers)).

## A worked example

Call the provider localstudio and use the real identifier exposed by your running local server as its model entry. The selectable reference is localstudio followed by a slash and that model ID. Give it a small function to explain. A display name can make the selector friendlier, but should not disguise which backend model receives the request.

| Check | Record |
| --- | --- |
| Configuration object | providers, not an unverified configuration copied from another major generation. |
| Runtime package | @opencode/ai/providers/openai-compatible with settings.baseURL for the existing endpoint. |
| Selection | The explicit provider/model reference visible in the current session. |

## Reading the failure correctly

A configuration field affects behavior only when supported by the selected package. If the model is absent, inspect provider ID, model entry, and active configuration before changing the server. A tool permission denial after a successful answer belongs to the permission layer and does not establish that custom provider integration failed ([OpenCode V2 Config](https://opencode.ai/v2/docs/config)).

## What completes the check

Retain the minimal provider entry and a successful read-only response. Introduce agent-specific permissions separately, preserving a baseline that proves model selection without authorizing unnecessary repository actions.

Related background: [Reproducible inference stacks: preserving a GPU pilot’s result](/journal/software-stack-reproducibility/), [Coding LLMs on 12GB VRAM: Budget Context and Headroom](/journal/coding-llm-12gb-vram/).