OpenCode Integration

Overview

OpenCode is a terminal-based AI coding assistant in the same lane as Claude Code and Aider. It loads custom providers through the @ai-sdk/openai-compatible npm adapter, which talks to any OpenAI-compatible API.

Erebine exposes OpenAI-compatible Chat Completions and Responses API endpoints, so OpenCode loads as a provider entry, not a fork. Point it at your endpoint, supply an API key, and drive your own models from the terminal.

OpenCode 2 and OpenCode 1

Both versions read opencode.json from the same places: ~/.config/opencode/, your project root, and .opencode/ inside it. OpenCode 2 renamed most config blocks, so the Client tab on your workspace offers two downloads:

• OpenCode v2 writes the native OpenCode 2 shape and ships an AGENTS.md with the Erebine tool-use rules.
• OpenCode v1 writes the OpenCode 1 shape and points OpenCode at the hosted rules file.

OpenCode 2 still reads an OpenCode 1 file, but OpenCode 1 cannot read an OpenCode 2 file. The two are not installed side by side, so keep the v1 bundle until you move, then switch to v2. The OpenCode migration guide lists every change; these are the ones in the Erebine bundle:

Prerequisites

• An OpenCode 2 or OpenCode 1 installation (install script, npm, or Homebrew)
• A Erebine account with an active endpoint
• An API key with inference scope

Installing OpenCode 2

Installing OpenCode 1

Both versions install the same opencode command. Remove a package-managed OpenCode 1 before you install OpenCode 2.

Creating an API Key

In your Erebine dashboard, navigate to Settings > API Keys and create a new key with the inference scope. Copy the key, you will need it for the configuration file.

Finding Your Endpoint URL

Your endpoint URL follows the format:

Replace WORKSPACE_ID with your ws_-prefixed workspace ID and ENDPOINT_SLUG with the slug shown on your endpoint's detail page. The project ID (proj_ABC123) is visible in your dashboard URL and project settings. The workspace prefix scopes the request to that workspace; this is the form the downloaded config uses.

To route across every generative endpoint in a workspace instead of naming one slug, use the semantic-routed base URL. The router picks the endpoint that best matches each request:

Replace WORKSPACE_ID with your ws_-prefixed workspace ID. See Semantic Router for the full request shape.

The router picks the endpoint per request, so the serving model can change between turns of one session. The X-Erebine-Routed-Model response header names what served each turn. A session that replays its history verbatim stays on one model without any extra configuration; see Pin a Conversation for what changes that. Do not pin a fixed X-Conversation-Id in the provider's headers -- a config header is one constant value, and every session would share one affinity key.

To choose the model yourself on every request, use the direct base URL:

The model travels in the request payload, not the path, so one base URL reaches every model in the project. List the ids it accepts with GET /proj_ABC123/WORKSPACE_ID/_direct/v1/models and send one verbatim as the model field. One config then covers your whole workspace: the downloaded opencode.json lists every model under providers.erebine.models (OpenCode 2) or provider.erebine.models (OpenCode 1), and they all appear together in opencode's model picker. Full reference: Direct Model Dispatch.

Configuration

Create or edit the OpenCode configuration file at ~/.config/opencode/opencode.json. The examples below configure Erebine as a custom provider, first in the OpenCode 2 shape, then in the OpenCode 1 shape. Use the one that matches your install.

OpenCode 2

The downloaded v2 bundle adds the mcp.servers block (see MCP) and an AGENTS.md file (see Instructions). Check the result with opencode mcp list, then pick an Erebine model with /models.

OpenCode 2 sends model and MCP requests from a shared background service. If you write the key as "{env:EREBINE_API_KEY}" instead of pasting it, a shell export reaches that service only when the same shell started it. Give the service the variable with opencode service set env EREBINE_API_KEY <key>.

OpenCode 1

Responses API Endpoint

OpenCode can also use the Responses API endpoint for multi-turn conversations with server-managed state. The base URL is the same, the OpenAI SDK automatically selects the correct endpoint based on the method called (client.responses.create() vs client.chat.completions.create()).

No configuration changes are required in opencode.json to use the Responses API. The same baseURL serves both Chat Completions and Responses endpoints.

Per-Project Configuration

You can also place an opencode.json file in your project root. Project-level configuration overrides the global config at ~/.config/opencode/opencode.json, in both versions.

MCP

OpenCode also speaks the Model Context Protocol over streamable HTTP. Add the Erebine MCP server to the same opencode.json file, under mcp.servers in OpenCode 2 or directly under mcp in OpenCode 1, and the full workspace tool catalog (memory, intelligence, artifacts, code, governed execution) becomes available to the agent on the next session.

Code Mode is off in the Erebine bundle. OpenCode 2 routes MCP tools through Code Mode by default, where the model writes JavaScript that calls them. codemode: false on the erebine server puts the Erebine tools on the model's native tool list instead, as OpenCode 1 does. To turn Code Mode back on for this server, set codemode to true or delete the line.

Replace placeholders with values from your project. <workspace_external_id> is the ws_-prefixed workspace identifier, not the project id already present in the URL; list candidates with erectl workspaces list. The MCP block coexists peacefully with the provider block above; chat-completions calls continue to flow through the OpenAI-compatible adapter while tool-call traffic reaches the workspace surface over MCP.

See the general MCP integration documentation for the full tool catalog, the governed-execution model, and the security gates that apply to every MCP request.

Compaction

The downloaded bundle emits a top-level compaction block. OpenCode 1 gets both flags; OpenCode 2 has no prune setting and gets auto only:

auto tells OpenCode to summarise older turns once the session approaches the model's context ceiling; prune lets OpenCode drop redundant tool-call output from the summarised transcript. The defaults match Erebine's posture on auto-summarisation. Set either flag to false if you need verbatim transcript retention (long debugging sessions, audit replay). Expect higher token spend on long sessions in that mode.

Instructions

Both bundles give the model a short project-rules block that nudges it to invoke the workspace MCP tools (memory, intelligence, artifacts, code, governed execution) rather than ask the user, and to persist load-bearing decisions back into the workspace. The two versions load it differently.

OpenCode 2 reads project guidance from AGENTS.md only, so the v2 bundle ships the rules as an AGENTS.md file. Save it at your project root. If your project already has an AGENTS.md, append the Erebine rules to it instead of replacing it. OpenCode 2 accepts an instructions field but does not load it.

OpenCode 1 gets a top-level instructions list holding the URL of the hosted rules file, https://erebine.ai/docs/mcp/opencode-rules.md. OpenCode fetches it at launch and adds it to every session's context.

Edit or remove the rules to taste: trim AGENTS.md, or replace the URL with a local file of your own. Re-downloading the bundle restores the canonical wording.

Field Reference

The following tables describe each field in the downloaded configuration bundle under its OpenCode 1 name. OpenCode 2 and OpenCode 1 maps each name to its OpenCode 2 form.

// providerProvider Options

// modelModel Options

The per-model dictionary key (e.g., my-endpoint-slug) is the local alias OpenCode shows in its picker and the second half of the provider/model id (the full id has the shape erebine/<endpoint-slug>). The name field beneath it is the deployed model identifier the inference endpoint expects to see in the request body.

// rootTop-Level Fields

// mcpMCP Fields

Supported Features

The following features have been validated with the Erebine API and the @ai-sdk/openai-compatible adapter.

Streaming (SSE)

OpenCode uses Server-Sent Events (SSE) streaming by default. Erebine's streaming implementation follows the OpenAI specification:

• Each chunk includes id, object, created, model, and choices fields
• Content is delivered via choices[].delta.content
• finish_reason is null until the final content chunk
• The data: [DONE] sentinel terminates the stream
• The final chunk includes a usage object with prompt_tokens, completion_tokens, and total_tokens

Tool Calling

OpenCode drives file operations, shell commands, and code editing through tool calling. Erebine forwards tools and tool_choice to the model unchanged, and relays the model's tool-call frames back to OpenCode verbatim:

• The tools and tool_choice request fields are sent to the model
• Tool call responses include choices[].delta.tool_calls with id, type, function.name, and function.arguments
• Streaming tool calls accumulate arguments across chunks
• finish_reason: "tool_calls" is set when the model decides to call tools
• Multi-turn tool interactions (the tool message role) are passed through correctly

Reasoning Content

Some models (e.g., DeepSeek-R1, QwQ) emit reasoning or "thinking" content alongside their responses. The downloaded bundle declares this surface with a per-model block carrying the default reasoningEffort (settings in OpenCode 2; options plus reasoning: true in OpenCode 1); OpenCode displays reasoning content in a collapsible section.

• Erebine returns reasoning on both reasoning and reasoning_content in the response, never inside content
• Reasoning content is model-dependent, non-reasoning models omit the reasoning block (and report reasoning: false in OpenCode 1)

Finish Reason Mapping

Passthrough

OpenCode owns the conversation. Erebine serves it as sent: your system prompt stays at index 0, your tool definitions and tool_choice are honored verbatim, no tool call runs that the model did not emit, and one OpenCode request is one model turn. Nothing is inserted or rewritten behind OpenCode's back; the only exception is an augmentation you opt into through the provider's headers (see below).

Erebine's own agentic harness is opt-in. If you want it, add X-Erebine-Augment: on to the provider's headers: headers in OpenCode 2, options.headers in OpenCode 1. Individual features are addressable one at a time; see Passthrough and Augmentation.

One augmentation is on by default in the downloaded bundle: X-Erebine-Augment-Corrective-Retries: on. It lets Erebine retry a malformed or empty model turn a bounded number of times before returning it, so a single bad generation does not surface as a failed request. Remove that entry from the provider's headers for strict passthrough where every model turn is returned exactly as first produced.

max_tokens

OpenCode may request a max_tokens value that exceeds what is left of your model's context window. The value is sent verbatim, so the request returns 400 context_length_exceeded rather than a quietly shortened answer. Lower max_tokens in the model config, use an endpoint with a larger context window, or send X-Erebine-Augment-Max-Output-Tokens-Clamp: on to have Erebine fit the value to the remaining context.

Tools on a Model Without Tool Support

OpenCode always sends tools. An endpoint whose model has no tool-call support returns 400 rather than answering as though no tools were sent. Route OpenCode at a tool-capable model.

Limitations

Unsupported OpenAI Extensions

• response_format (structured outputs / JSON mode), support depends on the model deployed on your endpoint
• seed, passed through but determinism depends on model support

Reasoning Content Availability

Reasoning content (reasoning / reasoning_content in the response delta) is only available for models that produce it (e.g., DeepSeek-R1, QwQ). For non-reasoning models the downloaded bundle omits the reasoning settings (OpenCode 2) or emits reasoning: false and omits the options block (OpenCode 1).

Troubleshooting

401 Unauthorized

The API key is missing, invalid, or does not have the inference scope.

• Verify the API key is set on settings.apiKey (OpenCode 2) or options.apiKey (OpenCode 1), not in the provider's headers. The @ai-sdk/openai-compatible adapter only reads that field; a key tucked under the headers is silently ignored.
• On OpenCode 2 with an {env:...} key, confirm the background service has the variable: opencode service get env.
• Re-download the bundle from the dashboard to make sure the key has not been rotated.
• Check that the key has the inference scope in your dashboard.

404 Not Found

The endpoint URL is incorrect or the endpoint does not exist.

• Verify the baseURL includes your project ID, workspace ID, and endpoint slug
• Confirm the URL ends with /v1
• Check that the endpoint is active in your dashboard

Model Not Found

The name field in your model config does not match the deployed model.

• The name field must exactly match the model name shown on your endpoint detail page
• Model names are case-sensitive

Connection Timeout

Requests may time out if no workers are available.

• Check your endpoint status in the dashboard
• Verify that at least one agent is healthy and connected
• For EIM nodes, confirm the agent process is running and registered

Tool Calls Not Working

If OpenCode reports that tool calling is unavailable:

• Verify your model supports function calling (not all models do).
• Check your endpoint status in the dashboard for any errors.
• Confirm the model's config block shows capabilities.tools: true (OpenCode 2) or tool_call: true (OpenCode 1). Re-downloading the bundle restores the capability flags resolved from the deployed model's family.

Reasoning Content Not Displayed

If reasoning content does not appear in OpenCode:

• Confirm the model config block shows a settings block (OpenCode 2), or reasoning: true and an options block (OpenCode 1). Re-downloading the bundle is the simplest way to restore them.
• Verify you are using a model that produces reasoning tokens (e.g., DeepSeek-R1, QwQ).
• Check that the model deployed on your endpoint supports reasoning output.

MCP: 403 scope_insufficient

The MCP route enforces workspace scoping separately from the inference key. A 403 with {"error":{"code":"scope_insufficient","type":"authentication_error"}} means the API key on the MCP Authorization header lacks one of the workspace scopes the requested tool requires.

• Re-download the bundle so the MCP block uses a key with the workspace scopes the dashboard provisions by default.
• Confirm X-Erebine-Workspace matches the workspace the key is bound to. A mismatch surfaces as "Workspace not bound" on prompts/get and resources/read.

MCP: 404 on Tool Calls

If api.erebine.ai/proj_ABC123/v1/mcp returns 404, either the bundle URL is wrong (extra path segments, wrong workspace) or MCP is not enabled on this deployment. Re-download the bundle and compare its URL. If a freshly downloaded bundle also gets a 404, MCP is off for the deployment: no client setting turns it on, so ask the deployment's operator.

429 Rate Limited

Inference and MCP traffic share the workspace rate-limit envelope. A 429 indicates the workspace is over its per-window quota. OpenCode does not auto-retry; back off and re-issue the request once the quota resets. The Retry-After response header (when present) lists the recommended wait in seconds.

Verifying Connectivity

Use curl to test your endpoint independently of OpenCode:

If this returns a valid response, the issue is in your OpenCode configuration. If it returns an error, resolve the API issue first.