# OpenCode

The SimpleLLM provider setup configures OpenCode with the model catalogue and your API key. You need Node.js 20 or newer for the setup package.

## Run the setup wizard

~~~bash
npx @simplellm/opencode-provider
~~~

The wizard fetches model metadata, asks for a SimpleLLM API key, validates it, and writes the provider configuration.

| File | Purpose |
| --- | --- |
| `~/.config/opencode/opencode.json` | OpenCode provider and model configuration |
| `~/.local/share/opencode/auth.json` | Stored API credential |

The wizard merges its provider configuration into the existing file. Back up a hand-edited configuration before running setup, and review the result if your installation uses custom paths or settings.

## Start a session

Choose an ID from the discovered model list. This example uses an ID present in the public catalogue on 2026-09-14:

~~~bash
opencode --model simplellm/Qwen3-Coder-30B-A3B-Instruct
~~~

The `simplellm/` prefix is OpenCode's provider selector; it is not part of the model ID in a direct HTTP chat request.

## Refresh models

Re-run the setup command after catalogue changes. The configuration is generated from the catalogue at setup time; it does not become permanently current just because the wizard was run once.

The package also includes a plugin that can show the remaining SC balance when a session starts. Check the [provider README](https://github.com/SimpleLLM/opencode-provider) for plugin integration details.

## Configuration variables

| Variable | Use |
| --- | --- |
| `SIMPLELLM_BASE_URL` | Provider setup base; defaults to https://api.simplellm.eu, without /v1 |
| `SIMPLELLM_API_KEY` | Key read by the plugin when set, overriding its stored key |

The setup base URL is different from the OpenAI SDK's `/v1` base URL because the provider also calls account and catalogue routes.

## Troubleshooting

If a model is missing, refresh the provider configuration and compare its ID with the public catalogue. If authentication fails, confirm the stored key and any overriding environment variable.

Long coding sessions resend context and can generate many tokens. Review [cache billing](/docs/billing.html) and [rate limits](/docs/limits.html), and make sure cancelling in the client actually closes its inference request.

Do not include the auth file or its contents in a support report.