> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode setup

> Connect your terminal coding agent with a custom Pearl provider.

## Before you start

Complete organization setup, make sure your account has inference credit, and create a key on the [API Keys page](https://platform.pearlresearch.ai/api-keys). Most coding agents need a tool-capable chat model; Aider's basic edit workflow does not require native tool calling. Image input and reasoning support depend on the model. These terminal examples use Bash or Zsh on macOS, Linux, or Windows through WSL.

Install OpenCode using its [official installation guide](https://opencode.ai/docs/), then run `opencode --version`. The config below uses the [custom provider format](https://docs.opencode.ai/docs/providers/#custom-provider) for OpenCode 1.x. Merge the configuration below into your existing config file.

## Get your connection settings

Open [Integrations](https://platform.pearlresearch.ai/integrations), select a model, then choose OpenCode. The screen uses your organization's region. The examples below use the public global endpoint; replace it with your regional endpoint and replace `YOUR_MODEL_ID` with the full model ID shown there. Choose one of the models listed for this integration.

Set your Pearl API key in the terminal where you run OpenCode:

```bash theme={null}
export PEARL_API_KEY="YOUR_PEARL_API_KEY"
```

## Configure OpenCode

```json ~/.config/opencode/opencode.json (merge into your existing config) theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "pearl": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Pearl Inference",
      "options": {
        "baseURL": "https://inference.pearlresearch.ai/v1",
        "apiKey": "{env:PEARL_API_KEY}"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "YOUR_MODEL_ID",
          "tool_call": true,
          "reasoning": true,
          "reasoning_options": [],
          "options": {
            "reasoning": {
              "effort": "high"
            }
          },
          "variants": {
            "low": {
              "reasoning": {
                "effort": "low"
              }
            },
            "high": {
              "reasoning": {
                "effort": "high"
              }
            },
            "max": {
              "reasoning": {
                "effort": "max"
              }
            }
          }
        }
      }
    }
  }
}
```

```bash List your configured Pearl models theme={null}
opencode models pearl
```

```bash Start OpenCode theme={null}
opencode --model 'pearl/YOUR_MODEL_ID'
```

Copying the configuration from Integrations includes your model's context and output limits when available. When setting `limit` manually, include both `context` and `output`. Use the selected model's limits from [the model catalog](/docs/reference/models.md).

The model's `options.reasoning.effort` sets the default reasoning effort, which OpenCode sends as Pearl's `reasoning` object. Don't use the `reasoningEffort` option: it sends the flat `reasoning_effort` field, which Pearl rejects with `400`. `variants` lists the levels the model serves, plus `none` on models that can turn reasoning off. Keep `reasoning_options` empty: otherwise OpenCode adds its own variants for some model names (DeepSeek among them), and those send `reasoning_effort`. Cycle the variants with `Ctrl+T` in the TUI, or pass `--variant` to `opencode run`. Levels the model doesn't serve round up to the next one it does (see [how effort levels map](/docs/reasoning.md#effort-mapping)).

## Select a Pearl model

OpenCode lists the models you add under `provider.pearl.models` in your config. To add another Pearl model, add its exact catalog ID to that object and restart OpenCode. Select it with `/models` or the startup command above.

If another endpoint or model is used, check the project's `opencode.json`, the `.opencode` directory, and `OPENCODE_CONFIG` and `OPENCODE_CONFIG_CONTENT`. These can override your global configuration. Merge the Pearl provider with your existing providers and preferences.

## Start using OpenCode

Open a project folder and start a new conversation. Ask OpenCode to explain a file or make a small change, then approve the file operations you want it to perform. You can review your usage and costs on the [Analytics page](https://platform.pearlresearch.ai/usage).

## Troubleshooting

* `401`: check the key and allow time for a newly created key to reach the inference gateway.
* `404`: copy the endpoint and exact model ID from Integrations. OpenAI base URLs end in `/v1`; the Anthropic SDK and Claude Code use the URL without that suffix.
* `402`: check your organization's credit and billing status.
* `429` or Anthropic `529`: respect retry instructions and reduce concurrency.
* For truncated output, check the output limit and reasoning budget. Increase limits only within the model's maximum output length.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.