OpenCode

Revision 1 · Updated 2026-11-12 · 3 min read

Connect OpenCode CLI to Runtoken through a custom Chat Completions provider.

Prerequisites#

Before you start, prepare:

• An OpenCode V2 CLI installation and a small test project. See the official CLI guide.
• A Runtoken platform API key.
• A Chat Completions model ID supporting tool calls.

This page uses the V2 configuration format. If you have V1 settings, follow the official migration guide before combining them with this example.

Connection settings#

Create opencode.json in the test project. If it already exists, merge the provider into it and retain unrelated settings. The following uses OpenCode's custom provider format.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "runtoken/YOUR_MODEL_ID",
  "providers": {
    "runtoken": {
      "name": "Runtoken",
      "env": ["RUNTOKEN_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.runtoken.net/v1"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "Runtoken coding model",
          "capabilities": {
            "tools": true
          }
        }
      }
    }
  }
}

Replace YOUR_MODEL_ID in both locations with the same model ID from the Runtoken catalogue. The runtoken/ prefix selects the local provider; it is not part of the platform model ID.

Declaring a capability does not add it to a model. Keep context limits, reasoning options and media capabilities aligned with the selected model rather than copying values from another provider.

Set credentials and launch#

Open a terminal in the test project, set the key, and start a standalone session. This gives the private server the environment from that terminal; an existing shared background server may have a different environment. See the CLI server modes.

export RUNTOKEN_API_KEY="YOUR_PLATFORM_KEY"
opencode --standalone

$env:RUNTOKEN_API_KEY = "YOUR_PLATFORM_KEY"
opencode --standalone

Replace YOUR_PLATFORM_KEY with your platform key. Keep the real key out of project configuration, prompts and screenshots; a command containing it can remain in shell history.

Open /models and select the model under Runtoken. Existing sessions can retain a model selected earlier, so check the active session instead of relying only on the configuration default. See model selection.

Check the connection and file task#

Send a short request, then find the corresponding Runtoken request record by time, key and model. Next, try a small file task in the test project.

Create greeting.py with a greet(name) function.
Return "Hello, " followed by the name, or "Hello, friend" when the name is empty.
Do not install dependencies or access the network.

Review the proposed file operation and approve the change when appropriate. Inspect the actual file, then ask OpenCode to read it again and change the empty-name greeting to Hello, guest.

Check that the second turn reads the existing file and changes the intended line. A proposed code block in a reply does not establish that the file was written or that tool results returned correctly.

Capabilities and limits#

This setup uses Chat Completions. Runtoken does not convert the request to Messages, Responses or Gemini when you change the model ID.

Model requests go to the configured gateway; local file and command tools run in OpenCode's execution environment. Retain normal tool permissions. Changing a provider does not grant access to local files or commands.

Troubleshooting#

Check the error response and active model before changing advanced options.

Restore settings and further reading#

Exit the test session and remove its temporary credential variable when finished.

unset RUNTOKEN_API_KEY

Remove-Item Env:RUNTOKEN_API_KEY -ErrorAction SilentlyContinue

Restore your previous default model and remove only the provider entries added for this test. Preserve other project settings.

For the request format, see OpenAI Chat. For configuration locations and validation, see OpenCode configuration and its configuration schema.