Configure a custom provider in OpenCode

Confirm configuration scope and compatibility

Website under maintenance. This is a planned setup guide: api.ubtl.net is a planned domain, no real API test has been performed, and OpenCode connectivity is unverified. Confirm the supported OpenAI-compatible protocol, paths, authentication requirements, and model identifiers before use.

Decide whether the configuration belongs at project or user scope, then locate the opencode.json actually read by your installed version. Back up the original and check whether another configuration source overrides it. Shared projects must not contain personal keys. The example below is a minimal provider definition to merge, not a replacement for existing tools, permissions, or other providers.

Define the package, endpoint, and model

provider.ubtl uses @ai-sdk/openai-compatible. The option is named baseURL with uppercase URL, and its planned value is https://api.ubtl.net/v1 rather than an arbitrary complete request path. Replace the models object key and the suffix of the top-level model value with the same confirmed model identifier; a friendly display name is not a substitute.

The apiKey value {env:UBTL_API_KEY} is an environment reference; preserve this exact syntax rather than borrowing another tool's notation. Later, place an isolated authorized key in the environment of the process launching OpenCode, not directly in JSON. If launching through a desktop shortcut or service, inspect its environment source separately so a missing variable is not mistaken for a model failure.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ubtl": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "UBTL",
      "options": {
        "baseURL": "https://api.ubtl.net/v1",
        "apiKey": "{env:UBTL_API_KEY}"
      },
      "models": {
        "YOUR_MODEL_ID": {"name": "UBTL model"}
      }
    }
  },
  "model": "ubtl/YOUR_MODEL_ID"
}

Restart, select the model, and troubleshoot

Save and restart OpenCode, check configuration parsing, then use /models to inspect the custom provider and model selection. A listed model does not prove remote support. Only after availability is confirmed should you send a short prompt from a test directory without private data, keeping tool permissions minimal. For authentication errors, inspect variable inheritance; for path errors, inspect baseURL and duplicated /v1; for model errors, inspect the full identifier and permissions. Redact keys in diagnostics. Restore the backup and restart again when reverting.