OpenCode Configuration

OpenCode is an open-source terminal coding agent. It talks to any OpenAI-compatible endpoint, so a CodeByAI API Key is all it needs — you declare this site as a custom provider and pick one of its models.

1. Install OpenCode

macOS or Linux:

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

If you prefer npm:

Copy
1
npm install -g opencode-ai

On Windows, WSL is recommended; a native install also works with npm install -g opencode-ai.

2. Create the configuration file

OpenCode reads opencode.json from ~/.config/opencode/ (global) or from your project root. Global configuration applies everywhere, so start there:

• macOS / Linux: ~/.config/opencode/opencode.json
• Windows: C:\Users\YourUserName\.config\opencode\opencode.json

Create the file with the following content:

Copy
1
{
2
  "$schema": "https://opencode.ai/config.json",
3
  "model": "codebyai/gpt-5.6-terra",
4
  "small_model": "codebyai/gpt-5.6-terra",
5
  "provider": {
6
    "codebyai": {
7
      "npm": "@ai-sdk/openai-compatible",
8
      "name": "CodeByAI",
9
      "options": {
10
        "baseURL": "https://www.codebyai.net/api/agent",
11
        "apiKey": "{env:CODEBYAI_API_KEY}"
12
      },
13
      "models": {
14
        "gpt-5.6-terra": {
15
          "name": "GPT-5.6 Terra",
16
          "limit": { "context": 200000, "output": 65536 }
17
        }
18
      }
19
    }
20
  }
21
}

A few details worth knowing:

• npm selects the wire protocol. @ai-sdk/openai-compatible means OpenCode calls /chat/completions.
• baseURL stops at /api/agent. Do not append /v1: the gateway forwards everything after that path to the upstream provider, and /api/agent/v1/chat/completions comes back as 404 page not found.
• Keys under models are the model IDs OpenCode will send. Add any model from the Model Plaza, for example gpt-6-astra.
• small_model is set explicitly on purpose. OpenCode otherwise looks for a cheaper model in the same provider and uses your main model when it cannot find one; naming it avoids title-generation errors.

3. Provide the API Key

Export the variable used in apiKey above (create a key on the API Keys page first):

Copy
1
export CODEBYAI_API_KEY="sk-proj-xxxx"

Add that line to ~/.zshrc or ~/.bashrc so every new terminal inherits it. If you would rather not use an environment variable, run opencode auth login once and paste the key there — the stored credential is used when apiKey is omitted.

4. Start OpenCode

Copy
1
cd your-project
2
opencode --model codebyai/gpt-5.6-terra

For a one-off question without the interactive interface:

Copy
1
opencode run -m codebyai/gpt-5.6-terra "summarise the structure of this repository"

Inside the interface, /models switches between the models you declared in the configuration.

5. Troubleshooting

• 404 page not found in the response: baseURL ends with /v1. Remove it.
• A reply that begins Hello! How can I help you with your software engineering tasks today? (HTTP 403): the gateway received no API key, so CODEBYAI_API_KEY is empty in the terminal that started OpenCode. A second 403, this one reading Invalid key!, means the key itself was deleted or mistyped.
• Insufficient balance: top up on the Wallet page.
• Claude models are served on the Anthropic-compatible endpoint that the Claude Code page of this guide configures; this page documents the OpenAI-compatible route.