Want to run OpenCode with your own API key? Create a BetterToken account and API key, then open the OpenCode setup guide and choose either /connect or opencode.json. Set the Base URL to https://www.bettertoken.ai/v1, use a current Model ID, send one short request, and verify the model, status, and token usage in the Dashboard.

What You Need to Run OpenCode in Russia

OpenCode is a terminal coding agent. It reads project files, works with a selected model, and can take actions in a repository. For a first run, prepare:

macOS, Linux, or Windows with access to an official installation method;
your own BetterToken API key;
a current Model ID from the BetterToken model catalog;
a test directory where you can safely inspect the agent response.

BetterToken handles the external API request in this workflow. It does not guarantee access to the OpenCode website, installer, GitHub, or updates. The BetterToken API Endpoint can be reached from Russia without a VPN, but that statement does not cover third-party websites or downloads.

Install OpenCode from an Official Source

Choose one method. Node.js is required only for the npm route.

macOS and Linux: Official Installer

curl -fsSL https://opencode.ai/install | bash

npm

npm install -g opencode-ai

Homebrew

brew install anomalyco/tap/opencode

OpenCode recommends its own tap for current releases. The brew install opencode formula is maintained by the Homebrew team and can update later.

Windows

The official documentation lists Chocolatey and Scoop:

choco install opencode

scoop install opencode

Verify the installation:

opencode --version

The command should print a version instead of command not found. This article does not pin a version number because releases change.

How `/connect` and `opencode.json` Work

OpenCode stores credentials separately from provider configuration.

/connect stores the API key in ~/.local/share/opencode/auth.json.
Global ~/.config/opencode/opencode.json defines providers and models for the user.
A project-root opencode.json changes settings for that project.

Configuration files are merged. On conflicts, later sources override earlier ones. For normal local setup, the relevant order is global config → OPENCODE_CONFIG → project opencode.json. Organization-managed settings use a separate highest-priority tier.

1. Store the API Key with `/connect`

Start OpenCode in a test directory:

mkdir opencode-first-test
cd opencode-first-test
opencode

Run this command in the TUI:

/connect

Choose Other, enter provider id bettertoken, and paste your API key into the credential field. Do not place a real key in a prompt, opencode.json, screenshot, or Git commit.

Exit OpenCode and confirm that the provider is registered:

opencode auth list

The command should list the provider without revealing the key.

2. Add the BetterToken Provider

For all projects, create or update ~/.config/opencode/opencode.json. For one repository only, place opencode.json in its root.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "bettertoken/YOUR_MODEL_ID",
  "provider": {
    "bettertoken": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BetterToken",
      "options": {
        "baseURL": "https://www.bettertoken.ai/v1"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "YOUR_MODEL_ID"
        }
      }
    }
  }
}

Replace YOUR_MODEL_ID with an exact identifier from the current BetterToken catalog. The same value must appear in model, as the models object key, and as its name. Do not append /chat/completions to the Base URL; OpenCode and @ai-sdk/openai-compatible construct the request path.

Automatic setup commands and current model-group limitations live in the BetterToken OpenCode documentation. The article keeps Model ID as a placeholder because model availability changes.

3. Check Which Configuration Wins

A project opencode.json can override the global model or provider. If OpenCode selects an unexpected endpoint, inspect these sources in order:

~/.config/opencode/opencode.json;
the OPENCODE_CONFIG value, when set;
opencode.json in the current project or the nearest parent up to the Git root.

Do not delete files at random. Compare model, provider.bettertoken.options.baseURL, and provider.bettertoken.models in every configuration you find.

Run and Verify the First Request

Restart OpenCode after editing JSON:

opencode

Open model selection:

/models

Choose bettertoken/YOUR_MODEL_ID. Send a request with an easy-to-check result:

Return only JSON: {"tool":"opencode","sum":4}. Do not modify files.

Treat the first request as verified only when all four checks pass:

OpenCode returns valid JSON and does not modify files;
the TUI shows bettertoken/YOUR_MODEL_ID;
BetterToken Dashboard records the expected model and status;
the Dashboard shows input, output, and applicable cache tokens with the corresponding charge.

The Dashboard is not described as a store for the complete prompt or response. This check covers usage metadata and token spend. If no entry appears, a different provider may have answered because of a configuration override.

Fix Common Errors

`opencode: command not found`

Close and reopen the terminal. For npm installation, confirm that the global npm directory is in PATH. Do not run a second installer before locating the first binary.

`401` or Credential Error

Run /connect again and choose provider id bettertoken. Check the result with opencode auth list. Do not paste the key into a command or JSON as a shortcut.

`404` or API Error

Set provider.bettertoken.options.baseURL to https://www.bettertoken.ai/v1. Do not append /chat/completions. Restart OpenCode and repeat the short request.

`model not found`

Compare the exact Model ID with the current documentation and model catalog. The top-level model must be bettertoken/YOUR_MODEL_ID, and provider.bettertoken.models must contain the same YOUR_MODEL_ID key.

OpenCode Uses a Different Model or Endpoint

This usually indicates a configuration override. Compare global config, OPENCODE_CONFIG, and the project file. Project configuration has higher priority among standard files. Restart OpenCode, then recheck /models and the Dashboard.

FAQ

Should I Store the API Key in `opencode.json`?

No. Use /connect for normal setup. OpenCode stores the credential in ~/.local/share/opencode/auth.json, so the configuration file can remain free of the real key.

Which Base URL Does OpenCode Need?

The BetterToken OpenAI-compatible provider uses https://www.bettertoken.ai/v1. It is a Base URL, so /chat/completions is not added manually.

Should I Use Global or Project `opencode.json`?

Use global config for a shared provider and model. Use a project file when one repository needs another Model ID or permission set. Project settings override global settings on conflicts.

Do I Need an OpenCode Account for the BetterToken Provider?

A custom provider uses the selected API service credential. BetterToken supplies its own API key but does not replace the OpenCode website, account, or other services. Check current tool requirements in the official OpenCode documentation.

OpenCode in Russia: Installation, API, and First Request