OpenCode coding agent on SovereignEG

Goal: run OpenCode (an open-source terminal coding agent, similar to Claude Code) with SovereignEG as the model provider.

Time: 10 minutes.

بالعربي: OpenCode بالعربي

OpenCode supports "custom providers" through the @ai-sdk/openai-compatible adapter — any server with /v1/chat/completions works, including SovereignEG.

Claude Code does not connect directly. SovereignEG speaks the OpenAI format (/v1/chat/completions), not Anthropic's /v1/messages, so Claude Code and the Anthropic SDKs get 404 route_not_found. Use OpenCode as shown here, or any OpenAI-compatible tool.

Step 1 — Install

# Linux / macOS / WSL
curl -fsSL https://opencode.ai/install | bash
 
# or with npm (all platforms)
npm install -g opencode-ai
 
# Windows
scoop install opencode      # or: choco install opencode

Check: opencode --version

Step 2 — Put your key in the environment

export SOVEREIGNEG_API_KEY="sk-..."          # Linux / macOS
$env:SOVEREIGNEG_API_KEY = "sk-..."          # Windows PowerShell

Step 3 — Create the config

Create opencode.json in your project folder (project config — simplest, works on every OS), or put it in ~/.config/opencode/opencode.json to use it in every project (global config, Linux/macOS).

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "sovereigneg": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "SovereignEG",
      "options": {
        "baseURL": "https://backend.sovereigneg.com/v1",
        "apiKey": "{env:SOVEREIGNEG_API_KEY}"
      },
      "models": {
        "SovereignEG/Qwen3.8-27B-FP8": {
          "name": "SovereignEG/Qwen3.8-27B-FP8 (SovereignEG)",
          "limit": { "context": 131072, "output": 8192 }
        }
      }
    }
  },
  "model": "sovereigneg/SovereignEG/Qwen3.8-27B-FP8"
}

On the Student plan or a Developer Pack, use "context": 92000 instead: see Plans with a free daily allowance below.

What each part means:

KeyMeaning
provider.sovereignegThe provider id you will see in /models. Any name works
npm@ai-sdk/openai-compatible = "talk OpenAI chat-completions format"
options.baseURLExactly https://backend.sovereigneg.com/v1: it ends with /v1. Not /v1/v1, and not /v1/chat/completions — OpenCode adds the endpoint itself
options.apiKey{env:NAME} reads the key from an environment variable — never write the key into the file
modelsOnly the models you list appear in the picker. Use the exact ids from /v1/models
limit.contextLets OpenCode manage the context window and compaction
model (top level)Default model in the form provider/model-id

Step 4 — Run it

cd your-project
opencode

Inside OpenCode:

  • /models — check that SovereignEG is listed and pick a model (from a normal terminal, opencode models prints the same list).
  • /init — makes an AGENTS.md describing your repo (commit it).
  • Type a task: "Add input validation to the signup form and write a test."
  • /undo and /redo — roll back or restore file changes.

Step 5 — Add more SovereignEG models

Copy any id from the model list into the models block:

curl -H "Authorization: Bearer $SOVEREIGNEG_API_KEY" https://backend.sovereigneg.com/v1/models

Plans with a free daily allowance

The Student plan and the Developer Pack include a free daily allowance that runs on our own GPUs in Egypt, so they have limits of their own on the plan's models. They are limits of the plan, not of the model, and every refusal says so:

  • Prompt size. The free allowance caps the prompt size on this model: today 100,000 tokens on the Student plan and 100,000 on a Developer Pack, and the refusal always names your plan's current cap. OpenCode resends the whole conversation with every step, so a long session grows past it and gets 400 prompt_too_long_for_plan. Set the context limit a little under the cap, and OpenCode compacts the conversation by itself before it gets there:

    "limit": { "context": 92000, "output": 8192 }
  • Requests per minute and at a time. A coding agent sends a new request after every tool call, so a busy session can reach the plan's requests-per-minute budget (today 20 on the Student plan and 120 on a Developer Pack, shared by all your API keys) or its limit on requests at a time (2 and 4). OpenCode then shows 429 rate_limit_exceeded or 429 concurrency_limit_exceeded: wait for the time in Retry-After and continue.

For long or busy sessions, pick a pay-as-you-go model instead; it is charged to your balance and the plan's limits do not apply to it. Rate Limits and the Student plan page explain how these limits work.

Troubleshooting

ProblemFix
Provider missing from /modelsJSON is invalid, or the file is in the wrong folder. Run opencode from the folder that holds opencode.json
401SOVEREIGNEG_API_KEY is not set in the same terminal you launched opencode from
400 model_not_foundThe model key inside models must be the exact id from /v1/models
404 route_not_foundThe base URL is wrong. It must be exactly https://backend.sovereigneg.com/v1. For the common mistakes (/v1 twice, no /v1, a base URL ending at /chat/completions) the error message names the fix
404 that mentions the Anthropic Messages APIThe tool speaks Anthropic's format (Claude Code, an Anthropic SDK, OpenCode's anthropic provider). Use the @ai-sdk/openai-compatible provider shown above
400 prompt_too_long_for_planYour plan's prompt cap (Student plan or Developer Pack): set limit.context a little under it, for example 92000 (Plans with a free daily allowance)
429 rate_limit_exceeded or concurrency_limit_exceeded on the Student plan or a Developer PackThe plan's request limits: wait for Retry-After, or use a pay-as-you-go model
Tool calls fail / model just talksPick a model that supports tools (supports_tools: true in /v1/models)
Answers get cut offRaise limit.output

Next: Hermes Agent

OpenCode | SovereignEG Docs