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 get404 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 opencodeCheck: opencode --version
Step 2 — Put your key in the environment
export SOVEREIGNEG_API_KEY="sk-..." # Linux / macOS$env:SOVEREIGNEG_API_KEY = "sk-..." # Windows PowerShellStep 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://remed-preprod-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:
| Key | Meaning |
|---|---|
provider.sovereigneg | The provider id you will see in /models. Any name works |
npm | @ai-sdk/openai-compatible = "talk OpenAI chat-completions format" |
options.baseURL | Exactly https://remed-preprod-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 |
models | Only the models you list appear in the picker. Use the exact ids from /v1/models |
limit.context | Lets 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
opencodeInside OpenCode:
/models— check that SovereignEG is listed and pick a model (from a normal terminal,opencode modelsprints the same list)./init— makes anAGENTS.mddescribing your repo (commit it).- Type a task: "Add input validation to the signup form and write a test."
/undoand/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://remed-preprod-backend.sovereigneg.com/v1/modelsPlans 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_exceededor429 concurrency_limit_exceeded: wait for the time inRetry-Afterand 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
| Problem | Fix |
|---|---|
Provider missing from /models | JSON is invalid, or the file is in the wrong folder. Run opencode from the folder that holds opencode.json |
401 | SOVEREIGNEG_API_KEY is not set in the same terminal you launched opencode from |
400 model_not_found | The model key inside models must be the exact id from /v1/models |
404 route_not_found | The base URL is wrong. It must be exactly https://remed-preprod-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 API | The 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_plan | Your 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 Pack | The plan's request limits: wait for Retry-After, or use a pay-as-you-go model |
| Tool calls fail / model just talks | Pick a model that supports tools (supports_tools: true in /v1/models) |
| Answers get cut off | Raise limit.output |
Next: Hermes Agent