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 example follows the API environment selected at the top of these docs:

• Sovereign, the default, uses https://sovereign.paranine.com/v1.
• Global uses https://sovereign.paranine.com/v1.

Choose the environment that matches your data-residency requirements. Residency is determined by the hostname, not by a request parameter.

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 Paranine reserves budget against an explicit max_tokens value before sending the request upstream.

When max_tokens is present, the gateway checks whether the key can cover the worst-case output cost:

max_tokens × output price per token

If that reservation exceeds the key's remaining credit limit, the request returns 402 insufficient funds, even when the response would probably have been short and inexpensive. When max_tokens is omitted, Paranine can instead cap the response at the largest output the remaining limit can afford.

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 worst-case reservation exceeds Rs 135, the request is rejected. 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