# Working with OpenCode

Connect OpenCode to Nodul Router with a plugin that leaves only the models of your key.

[OpenCode](https://opencode.ai) is a coding agent. The [nodul.code.plugin](https://github.com/nodul-app/nodul.code.plugin) plugin for OpenCode 2.2+ makes Nodul Router the only LLM provider:

- the model list comes from `GET /api/v1/models` called with your key (see [Models of your key](/docs/en/api/models#models-of-your-key)): if the key is limited to some models, OpenCode shows only those;
- the list has only models with the **Tools** capability: the OpenCode agent needs them on every step;
- other LLM providers are hidden; web search integrations (Exa, Firecrawl, Parallel, Tavily, TinyFish) stay;
- the default model is `ru-2/deepseek-v4.1-flash`; if your key cannot use it, the first available model is picked;
- the list refreshes on start, when the key changes and every 10 minutes.

## Install

1. Create an API key in a Router space (see [Quickstart](/docs/en/quickstart)).

2. Install [OpenCode Desktop](https://opencode.ai/download).

3. Install the plugin. On macOS:

   ```bash
   /Applications/OpenCode.app/Contents/Resources/opencode-cli plugin add 'git+https://github.com/nodul-app/nodul.code.plugin.git'
   ```

   If the `opencode` CLI is on your `PATH`, this is shorter: `opencode plugin add 'git+https://github.com/nodul-app/nodul.code.plugin.git'`.

4. Restart the background service and OpenCode:

   ```bash
   /Applications/OpenCode.app/Contents/Resources/opencode-cli service restart
   ```

5. Open **Settings → Providers → Nodul Router** and paste your Router key (`sk-nr-…`).

Instead of entering the key in the UI, you can set the `NODUL_ROUTER_API_KEY` environment variable.

## Update

OpenCode checks for a new plugin version once a day. To install it:

```bash
/Applications/OpenCode.app/Contents/Resources/opencode-cli plugin update
```

## Settings

If you need to, set plugin options in `~/.config/opencode/opencode.json`:

```json
{
  "plugins": [
    {
      "package": "git+https://github.com/nodul-app/nodul.code.plugin.git",
      "options": { "defaultModel": "deepseek/deepseek-v4.1-flash" }
    }
  ]
}
```

| Option         | Default                          | What it does       |
| -------------- | -------------------------------- | ------------------ |
| `defaultModel` | `ru-2/deepseek-v4.1-flash`       | Default model id   |
| `baseURL`      | `https://router.nodul.ru/api/v1` | Router API address |

## Good to know

- **Prices.** The router charges in PnP (1 PnP = 100 ₽, see [Pricing and billing](/docs/en/pricing-and-billing#pnp)), and OpenCode shows these numbers with a `$` sign. See the exact spend in the cabinet logs.
- **Budget.** The agent sends long prompts: set a budget on the key.
- **The first seconds after the service starts.** Other providers may flash by while the plugin loads.
- **Your own `provider` or `model` in `opencode.json`.** These settings apply after the plugin and override it. To see only Nodul Router, do not describe your own `nodul` provider or any other provider in the config.

## If you set up Nodul by hand before

Remove the `provider.nodul` block from `~/.config/opencode/opencode.json`, and also `model`, `small_model` and `enabled_providers` if you added them. Then unset the background service variables if you set them:

```bash
/Applications/OpenCode.app/Contents/Resources/opencode-cli service unset env OPENCODE_MODELS_PATH
/Applications/OpenCode.app/Contents/Resources/opencode-cli service unset env OPENCODE_DISABLE_FREE_MODELS
```

## Troubleshooting

| Symptom                                | What to do                                                                                                     |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Nodul Router asks you to sign in again | The router answered `401`: the key is wrong, disabled or expired. Enter a new key.                             |
| No models                              | Check that the key is entered and that the cabinet allows it at least one model with the **Tools** capability. |
| Other providers are visible            | Check `opencode.json`: it must not have its own `provider`. Restart the service (`service restart`).           |
| `402` on a request                     | The payer is low on funds or the key budget is spent.                                                          |

Other agents (Cursor, Cline, Roo Code, Kilo Code, Continue) connect as an OpenAI-compatible provider: see [IDE agents](/docs/en/ide-agents).