Opencode Desktop configuration

Setting OpenCode Desktop (Windows) with the ElettraGateway provider

Step-by-step instructions to configure OpenCode Desktop on Windows to use the ElettraGateway LLM gateway (https://llm-api-gw.elettra.eu/v1) and its models.

Prerequisites

• Windows 10/11 with OpenCode Desktop installed (v2.x)
• An ElettraGateway API key (sk-...)
• A plain-text editor (Notepad, Notepad++, VS Code…)

All steps below are for your Windows user account. <you> means your Windows user name, e.g. C:\Users\name.surname\....

---

Step 1 — Create the configuration file opencode.jsonc

OpenCode reads its global configuration from:

C:\Users\<you>\.config\opencode\opencode.jsonc

Create the folder and the file if they do not exist yet:

Paste the following content into opencode.jsonc and save it:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "elettragateway": {
      "name": "ElettraGateway",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://llm-api-gw.elettra.eu/v1"
      },
      "models": {
        "balanced": {
          "name": "balanced",
          "limit": {
            "context": 262144,
            "input": 262144,
            "output": 100000
          },
          "modalities": {
            "input": ["text", "image"]
          }
        },
        "top": {
          "name": "top",
          "limit": {
            "context": 1000000,
            "input": 1000000,
            "output": 100000
          },
          "modalities": {
            "input": ["text", "image"]
          }
        },
        "fast": {
          "name": "fast",
          "limit": {
            "context": 131000,
            "input": 131000,
            "output": 100000
          }
        }
      }
    }
  }
}

What this does

• Registers a custom, OpenAI-compatible provider named ElettraGateway pointing at the gateway URL.
• Declares the available models and their context limits (limit.context, limit.input, limit.output) — this is what OpenCode uses for context accounting.
• modalities.input: ["text", "image"] marks the models that accept images.

Tip: keep the API key out of this file (see Step 2). If you prefer a single file, you can instead put it under options as `"apiKey": "sk-...".

---

Step 2 — Register your API key

The recommended place for the key is the credentials file:

C:\Users\<you>\.local\share\opencode\auth.json

Create it with this content (replace the key with your own):

{
  "elettragateway": {
    "type": "api",
    "key": "sk-YOUR-KEY-HERE"
  }
}

---

Step 3 — Start (or reload) OpenCode Desktop

Launch OpenCode Desktop.

If the app was already running while you edited opencode.jsonc, please restart it.

---

Step 4 — MakeEnable the models visible in the model picker

The desktop app keeps its own list of which models appear in the model picker. Models that are not enabled there are hidden, even when they are correctly configured.

1. Click on the "three rows icon" (see screenshot), select File -> Settings. 
2. Go to Providers — "Choose which models appear in model picker".
3. 
4. Go to Models — "Choose which models appear in model picker".
5. Switch off everything not belonging to ElettraGateway, switch on the ElettraGateway models (top, balanced, `fast), or use Enable all models.

Settings → Models: enable the models that appear in the pickerg

---

Step 5 — Select a model and verifyTesting

1. OpenGo back to the main Opencode Desktop window clicking on the "back to app" on the top left corner.

The main screen presents 3 elements:

a: the selection box, allowing to switch between the build/plan phase; start in plan mode to analyse and plan the work, switch to build to actually edit existing files, perform actions, etc. b: when clicked, the model chooserselection withbox Ctrl+'allow (oryou clickchoose betweent the modelconfigured namemodels c: Opencode utilise "workspaces" to organise the work. A workspace is an existing folder in the composer).filesystem. Opencode will edit, write new files within that folder and will not asks for permissions. Pick one of the ElettraGateway models, e.g. top or balanced.

Send a test prompt and check that a reply arrives.

You can also mark models as favourites and use the Manage models dialog to hide models you never use (for example the free opencode/* models).

---

Troubleshooting

Symptom	Cause / fix
Only some models appear in the picker	Step 4: the model is disabled in Settings → Models (models not listed there are hidden by default).
No ElettraGateway provider at all	opencode.jsonc not found or not valid JSON/JSONC. Check the path from Step 1 and validate the syntax (a missing } or a trailing comma breaks the whole file).
401 / "API key required" errors	The key is missing or wrong — re-check auth.json (Step 2) or the apiKey field.
Changes to opencode.jsonc seem ignored	Use /reload in the app, or restart it. Config is merged from the global file plus any opencode.json(c) in the project folder.
Still stuck	Inspect the logs: C:\Users\<you>\.local\share\opencode\log\opencode.log (background service) and C:\Users\<you>\AppData\Roaming\ai.opencode.desktop\logs\ (app). Look for configuration normalization diagnostic warnings — they point to malformed config.

---

Appendix — where things live

What	Path
Global configuration (providers, models)	C:\Users\<you>\.config\opencode\opencode.jsonc
CLI/TUI settings (not used by the desktop)	C:\Users\<you>\.config\opencode\cli.json
API keys / credentials	C:\Users\<you>\.local\share\opencode\auth.json
Sessions database	C:\Users\<you>\.local\share\opencode\opencode.db
Service log	C:\Users\<you>\.local\share\opencode\log\opencode.log
Desktop app GUI settings (model visibility, layout, tabs)	C:\Users\<you>\AppData\Roaming\ai.opencode.desktop\drafts.sqlite
Desktop app logs	C:\Users\<you>\AppData\Roaming\ai.opencode.desktop\logs\

Appendix — useful keyboard shortcuts

Action	Shortcut
Open settings	Ctrl+,
Choose model	Ctrl+'
New session	Ctrl+T / Ctrl+N
Open project	Ctrl+O
Toggle terminal	`Ctrl+``
Command palette	search everything (Settings → Search everything)