Step-by-step guide to add any OpenAI-compatible provider (e.g. NVIDIA NIM) to OpenCode with auth.json key separation

opencode-custom-provider-guide.md

Adding a Custom Provider to OpenCode

OpenCode supports any OpenAI-compatible API via custom providers.
Your API keys are stored separately from config to prevent accidental leaks.

---

Architecture

File	Purpose
~/.config/opencode/opencode.json	Provider definition (name, baseURL, npm package, models)
~/.local/share/opencode/auth.json	Provider credentials (API keys, never committed)

---

Step 1: Add the Provider to opencode.json

Add a "provider" block (singular key) to your config:

// ~/.config/opencode/opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "nvidia": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://integrate.api.nvidia.com/v1"
      },
      "models": {
        "minimaxai/minimax-m2.5": {}
      }
    }
  }
}

Fields explained

Field	Required	Description
npm	Yes	SDK adapter — use @ai-sdk/openai-compatible for any OpenAI-compatible API
options.baseURL	Yes	The API's base URL (must end with /v1)
models	Yes	Map of model_id: {} — keys are the model identifiers the provider exposes

---

Step 2: Add the API Key to auth.json

Keys go in a separate file so they never end up in version control:

// ~/.local/share/opencode/auth.json
{
  "nvidia": {
    "type": "api",
    "key": "nvapi-YOUR_KEY_HERE"
  }
}

The key name ("nvidia") must match the provider name in opencode.json.

---

Step 3: Switch to the Provider

Restart OpenCode, then:

/models                           # list all available models
/model nvidia/minimaxai/minimax-m2.5   # switch to a specific model

---

Example: NVIDIA NIM (Full Walkthrough)

Why NVIDIA NIM?

NVIDIA's Inference Microservices API is fully OpenAI-compatible and offers models like minimaxai/minimax-m2.5 for coding tasks.

1. Get an API Key

Sign up at build.nvidia.com and generate an API key.

2. Provider Config (opencode.json)

{
  "provider": {
    "nvidia": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://integrate.api.nvidia.com/v1"
      },
      "models": {
        "minimaxai/minimax-m2.5": {}
      }
    }
  }
}

3. Auth Config (auth.json)

{
  "nvidia": {
    "type": "api",
    "key": "nvapi-YOUR_NVIDIA_API_KEY"
  }
}

4. Use It

/model nvidia/minimaxai/minimax-m2.5

---

Adding More Models to the Same Provider

Just add entries to the models map:

"nvidia": {
  "npm": "@ai-sdk/openai-compatible",
  "options": { "baseURL": "https://integrate.api.nvidia.com/v1" },
  "models": {
    "minimaxai/minimax-m2.5": {},
    "nvidia/llama-3.1-nemotron-70b-instruct": {},
    "mistralai/mixtral-8x22b-instruct-v0.1": {}
  }
}

---

Adding Multiple Providers

Each provider gets its own top-level key under "provider":

{
  "provider": {
    "nvidia": { "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "..." }, "models": { "model/id": {} } },
    "together": { "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "https://api.together.xyz/v1" }, "models": { "meta-llama/Llama-3-70b-chat-hf": {} } },
    "groq": { "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "https://api.groq.com/openai/v1" }, "models": { "llama-3.3-70b-versatile": {} } }
  }
}

And each needs a matching entry in auth.json:

{
  "nvidia": { "type": "api", "key": "..." },
  "together": { "type": "api", "key": "..." },
  "groq": { "type": "api", "key": "..." }
}

---

Common Pitfalls

Issue	Fix
Unrecognized key: "providers"	Use "provider" (singular), not "providers"
Model not showing in /models	Ensure the model ID matches what the provider exposes exactly
apiKey in opencode.json leaks	Move keys to auth.json — never put secrets in config
npm package not found	Run npm install or bun install in ~/.config/opencode/
Connection refused	Check that baseURL is correct and ends with /v1

---

TL;DR

# 1. Edit provider config
vim ~/.config/opencode/opencode.json
# Add "provider": { "myprovider": { "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "https://api.example.com/v1" }, "models": { "model-id": {} } } }

# 2. Add API key
vim ~/.local/share/opencode/auth.json
# Add "myprovider": { "type": "api", "key": "your-key" }

# 3. Restart OpenCode and select
/model myprovider/model-id

This is so stupid seems OpenCode doesn't have UI for this. Like literally they should have "Add custom URL" in connect provider.