Compatibility boundary

Start with OpenCode chat, then test agent features separately

OpenCode documents custom providers through opencode.json, a provider package, a base URL, credentials, and an explicit model map. This tutorial uses the official OpenCode OpenAI-compatible provider package with ScriptEngine’s verified bearer-authenticated /v1/models and /v1/chat/completions endpoints.

OpenCode can use tools, MCP, autocomplete, and other model capabilities. A successful chat-completions response does not prove that those additional request shapes work with every ScriptEngine model, so this guide intentionally declares text input and text output only.

Use OpenCode’s official provider documentation as the authority for version-specific configuration. The provider schema can change between OpenCode releases.

Requirements

Discover a model before writing the provider block

Install the current OpenCode release from its official distribution channel.
Create a private ScriptEngine API key and keep it in your environment or secret manager.
Query model discovery with the same key you will use in OpenCode.

Model discovery

export SCRIPTENGINE_API_KEY="YOUR_PRIVATE_KEY"
curl https://scriptengine.org/v1/models \
  -H "Authorization: Bearer $SCRIPTENGINE_API_KEY"

Copy a text-capable ID from the authenticated response and replace MODEL_ID_FROM_DISCOVERY. The public models catalog is useful for research, but your authenticated response is the source of truth for availability.

Configuration

Add ScriptEngine to opencode.json

OpenCode’s current custom-provider example uses the native OpenAI-compatible package. The model map is explicit because OpenCode cannot assume a catalog for a custom provider.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "scriptengine/MODEL_ID_FROM_DISCOVERY",
  "providers": {
    "scriptengine": {
      "name": "ScriptEngine",
      "env": ["SCRIPTENGINE_API_KEY"],
      "package": "@opencode-ai/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://scriptengine.org/v1"
      },
      "models": {
        "MODEL_ID_FROM_DISCOVERY": {
          "name": "ScriptEngine model",
          "capabilities": {
            "input": ["text"],
            "output": ["text"]
          }
        }
      }
    }
  }
}

Run /connect in OpenCode and choose the custom provider path when your version supports it. The credential ID must match scriptengine. Do not add tools: true, image input, or a Responses API setting unless the exact model and endpoint have been tested.

Verification

Prove the endpoint before giving OpenCode repository access

Run this harmless text-only request first. It separates key, model, and endpoint errors from an OpenCode configuration problem.

Chat-completions smoke test

curl https://scriptengine.org/v1/chat/completions \
  -H "Authorization: Bearer $SCRIPTENGINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID_FROM_DISCOVERY","messages":[{"role":"user","content":"Reply with exactly: OpenCode connected"}]}'

After the curl request succeeds, run OpenCode with a short prompt and a disposable repository. Keep MCP servers, file writes, and tool calls disabled until the selected model’s behavior is verified for your use case.

Troubleshooting

Resolve common OpenCode setup errors

401 or unauthorized: Confirm that SCRIPTENGINE_API_KEY is visible to the OpenCode process and that it is a ScriptEngine API key. Repeat the /v1/models request with the same environment.
Model is missing: Refresh model discovery and use the exact returned ID as the key in the provider’s models map and in the top-level model value.
Wrong URL or duplicated path: Use https://scriptengine.org/v1 as settings.baseURL. Do not include /chat/completions; the OpenAI-compatible package appends the route.
Agent, tools, or images fail: Keep the text chat configuration as the known-good baseline. Chat compatibility does not prove tools, images, embeddings, audio, or Responses API support.

Cost and safety

Keep coding experiments bounded

Repository context can make requests large. Start with a small prepaid balance, select a current model after checking the published rates, and monitor usage in the ScriptEngine workspace. The 86% figure is a dated, model-specific reference maximum, not a universal OpenCode discount.

Never commit an API key to opencode.json or a repository. ScriptEngine currently publishes no uptime or response-time SLA, so important workflows should implement their own timeout and recovery behavior.

Sources and next steps

Keep the provider block current

This page was checked August 4, 2026 against OpenCode’s provider documentation and ScriptEngine’s published API contract. Re-check the official reference after upgrading OpenCode.

Browse all integration guides Compare an OpenRouter alternative

Use OpenCode with ScriptEngine.