Connect OpenCode with Zeldoc.ai

Zeldoc.ai is available as a provider in OpenCode. This guide walks you through getting access to Zeldoc.ai and connecting it to OpenCode using your API key.

Prerequisites

OpenCode installed on your machine
A Zeldoc.ai account with an API key

Get an invitation to Zeldoc.ai

Zeldoc.ai is currently invitation-only. To get access:

Request an invitation from the Zeldoc.ai team.
Once your invitation is accepted, you'll receive access to your Zeldoc.ai account.

Generate an API key

After you have access to your Zeldoc.ai account:

Sign in to the Zeldoc.ai dashboard.
Navigate to the API keys section.
Create a new API key.
Copy the key — you'll need it in the next step.

Keep your key safe

Your API key grants access to your Zeldoc.ai account. Treat it like a password and never share it or commit it to version control.

Connect Zeldoc.ai to OpenCode

Zeldoc.ai is part of the provider list built into OpenCode. You can connect from the terminal or the desktop app — the credentials are shared across all OpenCode interfaces.

From the terminal

Open a terminal.
Run the following command:
```
opencode auth login
```
Search for Zeldoc in the provider list.
Select Zeldoc.
Paste your API key when prompted.

From the desktop app

OpenCode also ships as a desktop app (beta) for macOS, Windows, and Linux. To connect from the desktop app:

Open the OpenCode desktop app.
Open Settings and go to the Providers page.
Click Connect provider and search for Zeldoc in the provider list (it appears under Other).
Select Zeldoc to open the Connect Zeldoc dialog.
Paste your API key into the Zeldoc API key field and click Continue.

Once connected, Zeldoc appears under Connected providers with an API key tag.

Next, enable the model:

Go to the Models page in Settings.
Under the Zeldoc category, toggle Z-Code on.

You can now select Z-Code as your model from the model picker in any session.

Can't find Zeldoc in the provider list?

If you don't see Zeldoc in the provider list, you may have enabled_providers set in your config. Zeldoc is not included in the default enabled_providers list, so you'll need to add it:

{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["zeldoc"]
}

From the config file

You can also configure Zeldoc.ai directly in your OpenCode config file. This is useful when you want to keep your setup declarative or share it across environments. To learn more about the config file format and available options, see the OpenCode config docs.

Add the following to your opencode.jsonc (or ~/.config/opencode/opencode.jsonc for a global setup):

Use opencode.jsonc

We recommend the .jsonc extension over .json so you can add comments to document your config. OpenCode reads both, but comments make it easier to explain why each option is set.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "zeldoc": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Zeldoc.ai",
      "options": {
        "baseURL": "https://api.zeldoc.ai/v1",
        "apiKey": "{env:ZELDOC_API_KEY}"
      },
      "models": {
        "z-code": {
          "name": "Z-Code",
          "attachment": false,
          "reasoning": true,
          "tool_call": true,
          "temperature": true,
          "limit": {
            "context": 131072,
            "output": 131072
          },
          "modalities": {
            "input": ["text"],
            "output": ["text"]
          },
          "variants": {
            "high": {
              "reasoningEffort": "high"
            },
            "max": {
              "reasoningEffort": "max"
            }
          }
        }
      }
    }
  }
}

The config references your API key through the ZELDOC_API_KEY environment variable, so make sure it's set before starting OpenCode:

export ZELDOC_API_KEY=your-api-key

Persist the environment variable

Add the export line to your shell profile (e.g. ~/.bashrc or ~/.zshrc) so the key is available in every new terminal session.

Already authenticated? You can drop apiKey

If you connected interactively (via opencode auth login in the terminal or the desktop app's Providers page), OpenCode stores your key in ~/.local/share/opencode/auth.json and reads it automatically. In that case you can omit the apiKey option from the options block above.

You still need the rest of the provider block, though — npm, baseURL, and the models definition (including limit) don't come from auth.json, so they have to live in your config.

Seeing "encountered an error"? Set the context limit yourself

We're actively tuning how Z-Code is served to give customers the best experience, so the model's context limit may change from time to time. The current recommended value is 131072, as shown in the example above.

If you connected Zeldoc interactively (via opencode auth login or the desktop app's Providers page) and start seeing an "encountered an error" message, don't wait for the built-in provider defaults to update. Instead, define the provider in your own opencode.jsonc so you can set the current, correct context value yourself.

Since you already authenticated, you can leave out apiKey — OpenCode reads it from auth.json. A minimal override looks like this:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "zeldoc": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Zeldoc.ai",
      "options": {
        "baseURL": "https://api.zeldoc.ai/v1"
        // apiKey omitted — read from ~/.local/share/opencode/auth.json
      },
      "models": {
        "z-code": {
          "name": "Z-Code",
          "limit": {
            "context": 131072,
            "output": 131072
          }
        }
      }
    }
  }
}

This works for both the terminal and desktop versions of OpenCode. If lowering the value doesn't help, reach out to the Zeldoc.ai team for the latest recommended context limit.

Recommended config

When using Zeldoc.ai with OpenCode, we recommend locking down your config to ensure your data stays private and you don't accidentally use a different provider. Add these two options to your opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "share": "disabled",
  "disabled_providers": ["opencode"]
}

"share": "disabled" — Prevents conversations from being shared via share links. Your prompts and responses stay on your machine.
"disabled_providers": ["opencode"] — Removes the default OpenCode provider so you don't accidentally send requests to a model you didn't intend to use.

Disable web search

OpenCode's websearch tool sends your search queries to a third-party service (Exa AI). By default, the tool is only available when using the OpenCode provider — which we've disabled above — so it's already off.

If you've enabled web search manually via the OPENCODE_ENABLE_EXA environment variable, you can explicitly disable it in your config to make sure your queries never leave your machine:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "websearch": "deny"
  }
}

webfetch is separate

The webfetch tool fetches a specific URL you provide and doesn't send your data to a third party. It can stay enabled if you want the agent to be able to read web pages.

Combine with your Zeldoc.ai config

These options go in the same opencode.jsonc file as your Zeldoc.ai provider config. Merge them into a single object — don't create a second config file.

Verify the connection

To confirm that Zeldoc.ai is connected, run:

opencode auth list

You should see Zeldoc.ai listed among your authenticated providers. You're now ready to use Zeldoc.ai with OpenCode.

Prerequisites​

Get an invitation to Zeldoc.ai​

Generate an API key​

Connect Zeldoc.ai to OpenCode​

From the terminal​

From the desktop app​

From the config file​

Recommended config​

Disable web search​

Verify the connection​