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.

Prerequisites

• An OpenCode installation (npm, brew, or binary)
• A Erebine account with an active endpoint
• An API key with inference scope

Installing OpenCode

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 options.headers -- a config header is one constant value, and every session would share one affinity key.

Configuration

Create or edit the OpenCode configuration file at ~/.config/opencode/opencode.json. The following example configures Erebine as a custom provider:

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.

MCP

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

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.erebine 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:

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

The downloaded bundle inlines a top-level instructions string. OpenCode prepends that string to every session's system prompt before the host model sees the first user turn. The bundled content is a short project-rules block that nudges the model 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.

Operators may edit or remove the instructions string in their saved opencode.json. Re-downloading the bundle restores the canonical wording. If a future session feels over-eager to call tools, trim or rewrite the block locally, the field is plain text and OpenCode treats it as a verbatim system prefix.

Field Reference

The following tables describe each field in the downloaded configuration bundle.

// 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 via the per-model reasoning: true flag plus an options block carrying the default reasoningEffort; OpenCode displays reasoning content in a collapsible section.

• Erebine relays reasoning_content fields in the response as-is
• Reasoning content is model-dependent, non-reasoning models report reasoning: false and omit the options block

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 options.headers (see below).

Erebine's own agentic harness is opt-in. If you want it, add X-Erebine-Augment: on to options.headers in your provider block. 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 options.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_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 emits reasoning: false and omits the options block.

Troubleshooting

401 Unauthorized

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

• Verify the API key is set on options.apiKey, not options.headers.Authorization. The @ai-sdk/openai-compatible adapter only reads options.apiKey; a key tucked under options.headers is silently ignored.
• 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 tool_call: true. 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 reasoning: true and an options block. 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

The MCP endpoint is only mounted when the deployment has the MCP feature gate enabled (EREBINE_MCP_ENABLED). If api.erebine.ai/proj_ABC123/v1/mcp returns 404, either the bundle URL is wrong (extra path segments, wrong workspace) or the feature is off on this deployment.

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.