A Practical Guide to Using OpenCode IDE Extension with a Custom Provider

A coding assistant inside your editor is only useful if it can use the same model setup you already trust in the terminal.

OpenCode is interesting because the IDE Extension does not need to be treated as a completely separate integration. According to the Ace Data Cloud OpenCode IDE guide, the extension connects to the local OpenCode runtime and reuses the same Provider configuration used by the CLI. That makes it a practical path if you want one model configuration to work across Terminal, TUI, and editor workflows.

This guide walks through the setup pattern, the configuration file shape, and the minimal validation I would run before relying on it for real code edits.

What you can do

The OpenCode IDE Extension supports editors such as VS Code, Cursor, Windsurf, and VSCodium. The important boundary is that the extension reuses the OpenCode local runtime and Provider configuration; it does not mean the host editor itself has native Ace Data Cloud support.

That distinction matters. A terminal chat request proving your Provider works is not the same thing as proving the IDE can read files, propose edits, or invoke tools correctly. Treat the first setup as a small integration test, not just a login check.

How it works

The Provider configuration lives in opencode.json or opencode.jsonc. The documented setup uses the OpenAI-compatible AI SDK provider package and points it at the Ace Data Cloud API base URL.

Here is the core configuration shape from the guide:

{
  "provider": {
    "acedatacloud": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://api.acedata.cloud/v1",
        "apiKey": "{env:ACEDATACLOUD_API_KEY}"
      },
      "models": {
        "MODEL_ID": { "name": "MODEL_ID" }
      }
    }
  },
  "model": "acedatacloud/MODEL_ID"
}

The fields worth double-checking are:

• provider.acedatacloud: the custom provider namespace used by OpenCode.
• npm: set to @ai-sdk/openai-compatible.
• options.baseURL: set to https://api.acedata.cloud/v1.
• options.apiKey: read from {env:ACEDATACLOUD_API_KEY} instead of hardcoding a token.
• models.MODEL_ID: define the model ID you want to use.
• model: select it through the namespaced value acedatacloud/MODEL_ID.

In practice, I would commit the opencode.jsonc structure if it is part of a shared dev environment, but keep the actual API token only in the developer or CI environment.

Step 1: configure the Provider first

Start with the Provider before thinking about the editor. Create or update opencode.jsonc, choose a real MODEL_ID from the model catalog you plan to use, and export the token as an environment variable:

export ACEDATACLOUD_API_KEY="your-token-here"

Then run OpenCode from the terminal and perform a tiny smoke test. I like using a boring prompt because it makes failures obvious:

Reply only OK

If the CLI cannot answer that, do not move on to the IDE Extension yet. Fix the Provider config first: base URL, environment variable name, and model ID are the likely places to check.

Step 2: install the IDE Extension

Once the Provider works in the terminal, install the IDE Extension. The guide gives two paths:

1. Run opencode in the integrated terminal of the editor and follow the official process to install the Extension automatically.
2. Or install it manually from the corresponding Marketplace.

After installation, reload the editor. That reload step is easy to skip, but it is often the difference between testing the current extension process and testing stale state from before the install.

Step 3: run minimal validation inside the editor

Now run the same simple check from the OpenCode Extension:

Reply only OK

This confirms that the extension can reach the local OpenCode runtime and that the runtime is using the configured Provider and model.

But I would not stop there. The document explicitly warns that successful ordinary chat cannot replace validation for file reading, editing, and tool invocation. A minimal validation set could be:

1. Ask the extension to summarize the currently open file.
2. Ask it to propose a small edit without applying it.
3. Ask it to apply a tiny, reversible change in a test file.
4. If your workflow uses tools, run one tool-based request and record the result.

Keep these tests intentionally small. The goal is not to benchmark intelligence; it is to verify the request chain between the editor, OpenCode runtime, Provider, and selected model.

Current boundaries to keep in mind

There are three boundaries I would document for a team rollout.

First, the Provider capability comes from the OpenCode runtime. The host editor is connecting to that runtime; it is not independently implementing Ace Data Cloud support.

Second, VS Code and forks such as Cursor, Windsurf, and VSCodium may differ by extension version and request behavior. Record the editor name and extension version when you validate the setup.

Third, validate the actual workflows you expect developers to use. Chat, file reading, edits, and tool invocation are different integration surfaces. Passing one does not automatically prove the others.

A rollout checklist

For a single developer, the setup is just a few steps. For a team, I would make it repeatable:

• Add an example opencode.jsonc with ACEDATACLOUD_API_KEY as an environment reference.
• Decide and document the MODEL_ID value.
• Keep the token out of source control.
• Install or update the IDE Extension.
• Reload the editor.
• Run Reply only OK from the extension.
• Validate file reading and a safe edit in a test file.
• Record editor name, editor version, extension version, and model ID.

That gives you a boring but reliable integration path: one Provider configuration, reused by the OpenCode runtime, then exercised through the IDE where developers actually work.

For the full configuration notes and current boundaries, see the source guide: OpenCode IDE Extension Setup Guide.