Use Paranine with OpenCode

Connect OpenCode to Paranine through the OpenAI-compatible chat completions API. This guide uses an environment variable for the API key, keeps the secret out of your configuration file, and explains the budget behavior that commonly affects coding agents.

Note: These steps were tested on macOS. Linux uses the same configuration path. On Windows, the path starts at %USERPROFILE%\.config\opencode\.

1. Create an API key

Sign in, open API keys, and create a key for OpenCode. If you have not used Paranine before, start with the Quickstart.

Export the key so OpenCode can read it without storing the secret in opencode.jsonc:

export P9_API_KEY="sk_p9_•••••••"

Restart your terminal after adding the export, or run the command in your current shell before opening OpenCode.

2. Configure the Paranine provider

Use OpenCode's custom OpenAI-compatible provider, @ai-sdk/openai-compatible. It sends requests through /v1/chat/completions, which is the API surface Paranine supports. Do not use the built-in openai provider for this connection because that integration uses the Responses API.

Create or update ~/.config/opencode/opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "paranine": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Paranine",
      "options": {
        "baseURL": "https://sovereign.paranine.com/v1",
        "apiKey": "{env:P9_API_KEY}"
      },
      "models": {
        "paranine/gpt-oss-120b(Global)": {
          "name": "P/9 gpt-oss-120b (Global)"
        },
        "paranine/Kimi-K3(Global)": {
          "name": "P/9 Kimi K3 (Global)"
        }
      }
    }
  }
}

The key under models must be the exact Paranine route ID sent to the API. The name value is only the label OpenCode displays, so you can make it more descriptive without changing the request. Add only the routes you plan to use; the model catalogue lists every available ID and price.

The API is at https://sovereign.paranine.com/v1. Where a request is processed depends on the model you choose, not on the address: see Data residency.

OpenCode's official provider guide documents the same custom-provider structure and @ai-sdk/openai-compatible package: OpenCode providers.

3. Select a model

Restart OpenCode after saving the configuration, then run:

/models

Choose the Paranine provider and select one of the routes you added. OpenCode groups the route under the provider; the model key in opencode.jsonc remains the exact ID sent to Paranine.

4. Allow enough credit-limit headroom

Agentic tools often request a much larger output allowance than a simple chat client. This matters because, before each request runs, Paranine checks that the key can cover its maximum cost.

When max_tokens is set, that maximum is:

estimated prompt cost + max_tokens × output price per token

If it is more than the key's remaining credit limit or your organisation's balance, the request returns 402 insufficient funds, even when the reply would have been short and cheap. Requests running at the same time each need that headroom. Without max_tokens, the reply is capped at the model's default length, so a long answer can stop early with finish_reason: "length".

OpenCode can therefore receive a 402 while a small curl request succeeds with the same key. The difference is the explicit output allowance, not necessarily the account balance.

For example, a key with Rs 65 spent against a Rs 200 credit limit has Rs 135 of headroom. If OpenCode's maximum cost for a request is more than Rs 135, the request is refused. Raising that key's limit to Rs 300 gives it Rs 235 of headroom and can allow the same request without changing the model or account balance.

Important: Give an OpenCode key meaningful headroom above the average response cost. A tightly sized limit can fail intermittently as the requested output allowance changes.

5. Verify the connection

Send a message through OpenCode, then open Request logs in the Paranine dashboard. The call should appear with its model, latency, token counts, and cost in rupees.

If no request appears, work through the checks below before changing the provider definition.

Troubleshooting