Documentation
Documentation menu

OpenCode

Connect OpenCode to Etage: prepare your key, configure the client and select a model on Windows or macOS/Linux.

On this page

Before you start

You need OpenCode installed, an Etage API key and available credits. Create a key in your account and check model access. This guide manually configures your own Etage connection rather than selecting another service from a provider list.

1. Open the configuration folder

OpenCode must already be installed. Fully quit it before editing. If configuration exists, make a backup first. The examples below are for a new setup; in an existing file merge only the required Etage fields without removing other connections, security settings or sign-in data.

Windows: press Win + R and open %USERPROFILE%\.config\opencode. If the folder is missing, create it with the PowerShell command below (not CMD), then edit the file in Notepad. On macOS open Terminal; on Linux use your terminal. The second tab creates the folder and opens the file in nano; another text editor also works. Examples use the standard home directory; if you changed the client configuration location, use your own path.

PowerShell
New-Item -ItemType Directory -Force -Path "$HOME\.config\opencode" | Out-Null
notepad "$HOME\.config\opencode\opencode.json"

2. Write opencode.json

Create opencode.json and paste the JSON below. This is a short two-model example, not the full catalogue. The API base is https://api.etage.one/v1. The etage block uses Responses, while etage-chat uses Chat Completions. Keep the adapters separate; one format does not replace the other.

JSON
{
  "model": "etage/gpt-6.1-sol",
  "small_model": "etage/gpt-6.1-sol",
  "provider": {
    "etage": {
      "npm": "@ai-sdk/openai",
      "name": "Etage",
      "options": {
        "baseURL": "https://api.etage.one/v1",
        "apiKey": "YOUR_API_KEY"
      },
      "models": {
        "gpt-6.1-sol": {
          "id": "gpt-6.1-sol",
          "name": "gpt-6.1-sol"
        }
      }
    },
    "etage-chat": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Etage Chat",
      "options": {
        "baseURL": "https://api.etage.one/v1",
        "apiKey": "YOUR_API_KEY"
      },
      "models": {
        "deepseek-v4.1-flash": {
          "id": "deepseek-v4.1-flash",
          "name": "deepseek-v4.1-flash"
        }
      }
    }
  }
}

3. Set your key and select a model

Replace both YOUR_API_KEY placeholders with your Etage key. By default model and small_model are etage/gpt-6.1-sol. For Chat Completions change both to etage-chat/deepseek-v4.1-flash. In OpenCode use /models to select models from this example. Add other models separately using their exact Model ID and compatible format: this example does not promise access to every model.

In an existing configuration merge provider and the required fields, without duplicate JSON keys or deleting other connections. Check old baseURL, apiKey and authentication settings before switching. The key must allow the selected model.

Images in OpenCode 2.2.2+

Image generation and editing use the experimental_image_generate tool, not the primary chat model. Add providers and experimental from this example at the top level of the same opencode.json, preserving the existing provider, model and small_model. Do not select an image model through /models as your chat model.

Replace YOUR_API_KEY with the same Etage key. Keep only image models allowed for that key. The default is Flare with #auto; if only Sunburst is available, set experimental.image_generate.model to etage-image/gpt-image-2.5-sunburst#auto. Omit this block when image access is absent or unknown.

The auto, low, medium, high, xhigh and max variants set settings.quality, not chat reasoningEffort. For example, use etage-image/gpt-image-2.5-flare#high in the tool's model field or experimental.image_generate.model. A request in prompt text does not replace this parameter. A configured variant does not verify the API's effective output quality.

JSON
{
  "providers": {
    "etage-image": {
      "name": "Etage Images",
      "package": "@opencode/ai/providers/openai-compatible/images",
      "settings": {
        "baseURL": "https://api.etage.one/v1",
        "apiKey": "YOUR_API_KEY"
      },
      "models": {
        "gpt-image-2.5-flare": {
          "name": "GPT Image 2.5 Flare",
          "type": "image",
          "capabilities": { "tools": false, "input": ["text", "image"], "output": ["image"] },
          "variants": [
            { "id": "auto", "settings": { "quality": "auto" } },
            { "id": "low", "settings": { "quality": "low" } },
            { "id": "medium", "settings": { "quality": "medium" } },
            { "id": "high", "settings": { "quality": "high" } },
            { "id": "xhigh", "settings": { "quality": "xhigh" } },
            { "id": "max", "settings": { "quality": "max" } }
          ]
        },
        "gpt-image-2.5-sunburst": {
          "name": "GPT Image 2.5 Sunburst",
          "type": "image",
          "capabilities": { "tools": false, "input": ["text", "image"], "output": ["image"] },
          "variants": [
            { "id": "auto", "settings": { "quality": "auto" } },
            { "id": "low", "settings": { "quality": "low" } },
            { "id": "medium", "settings": { "quality": "medium" } },
            { "id": "high", "settings": { "quality": "high" } },
            { "id": "xhigh", "settings": { "quality": "xhigh" } },
            { "id": "max", "settings": { "quality": "max" } }
          ]
        }
      }
    }
  },
  "experimental": {
    "image_generate": { "model": "etage-image/gpt-image-2.5-flare#auto" }
  }
}

4. Save the configuration

Save as plain UTF-8 text. In Notepad choose All files, press Ctrl + S and check that .txt was not added to the filename. In nano: Ctrl + O → Enter → Ctrl + X. On macOS/Linux restrict access to key-containing files with the command below; do not publish them or their backups.

Fully quit OpenCode, including its tray process if it stays running. The next launch loads the updated configuration. Successful configuration does not make every model compatible with every client feature.

Bash
chmod 600 "$HOME/.config/opencode/opencode.json"

5. Start OpenCode

Open a terminal in your project folder and run the command. In the client use /models to select the configured Etage model.

Bash
opencode

Verify the connection

Check the selected model. Test with short text without secrets; requests spend credits. After a response, check Usage for a retained record. A missing record does not establish zero spending.

Troubleshooting

If the connection fails, check the following settings. Never send your key or full configuration to support.

  • 401/403: check your key, expiry, model access and available credits.
  • Model not found: use the exact Model ID and the correct Responses or Chat Completions adapter.
  • Configuration error: check JSON syntax, duplicate keys, UTF-8 and opencode.json without .txt.
  • Stale settings: fully restart OpenCode and check previous baseURL, apiKey and authentication settings.