In this article
OpenCode V2 custom providers use providers, a runtime package, settings.baseURL, and explicit provider/model references.
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).
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).
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).
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, Coding LLMs on 12GB VRAM: Budget Context and Headroom.