OpenCode

OpenCode is an open‑source coding agent for the terminal, your IDE, and the desktop. Because SCX.ai exposes an OpenAI‑compatible API, OpenCode talks to it as a custom provider — point it at our base URL, drop in your API key, and every model on your account is available to its agents.

OpenCode ships with two primary agents — plan (reads and reasons) and build (edits and runs) — and you can point each at a different model. That gives you two deployment postures:

  • Sovereign — both agents run entirely on SCX.ai. Nothing leaves your stack.
  • Hybrid — a frontier model plans, and a fast SCX.ai model executes the dozens of edits and test runs.

This guide connects OpenCode end‑to‑end and shows both configs side by side.

What you'll connect

AgentSovereignHybrid
plan (architect)scx/coderanthropic/claude-opus-4-7
build (executor)scx/MiniMax-M2.7scx/MiniMax-M2.7

Swap the model IDs for any chat model on your account — browse the catalogue.

Prerequisites

  • A SCX.ai API key — create one in the dashboard under API Keys.
  • Node.js 18 or later (only needed for the npm install path).
  • For the hybrid setup, a frontier provider key (e.g. an Anthropic key).

Export your key(s) so the config and CLI can read them:

bash
export SCX_API_KEY=your-scx-api-key
# Hybrid only — the frontier planner:
export ANTHROPIC_API_KEY=sk-ant-...

Quick connect

The fastest way in: install OpenCode, open the web UI, and add SCX.ai as a custom provider.

Install OpenCode

curl -fsSL https://opencode.ai/install | bash

Open the web UI

bash
opencode web

Add a custom provider

Go to Settings → Providers and add a new custom provider.

Enter your SCX.ai credentials

  • URL: https://api.scx.ai/v1
  • API Key: your SCX.ai API key (e.g. your-scx-api-key)
  • Model Name: any chat model on your account, for example MiniMax-M2.7

Start building

OpenCode now routes its requests through SCX.ai. Pick the model from the status bar and start a session.

Configure via opencode.json

For anything beyond a single model — assigning different models to different agents, version‑controlling the setup, sharing it with a team — use a config file. OpenCode reads opencode.json from the project root, falling back to ~/.config/opencode/opencode.json globally.

Create a workspace and drop a config in it:

bash
mkdir -p ~/opencode-demo && cd ~/opencode-demo

Both configs below register SCX.ai as an OpenAI‑compatible provider, expose a reasoning coder model and the fast MiniMax-M2.7 executor, and wire in the Context7 MCP server for live library docs. The only difference is who plans.

Sovereign — every request stays on SCX.ai.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  },
  "model": "scx/coder",
  "small_model": "scx/coder",
  "agent": {
    "plan":  { "mode": "primary", "model": "scx/coder" },
    "build": { "mode": "primary", "model": "scx/MiniMax-M2.7" }
  },
  "provider": {
    "scx": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "SCX.ai",
      "options": {
        "baseURL": "https://api.scx.ai/v1",
        "apiKey": "{env:SCX_API_KEY}"
      },
      "models": {
        "coder": {
          "name": "Coder",
          "reasoning": true,
          "tool_call": true,
          "limit": { "context": 191000, "output": 8000 }
        },
        "MiniMax-M2.7": {
          "name": "MiniMax-M2.7",
          "reasoning": true,
          "tool_call": true,
          "limit": { "context": 191000, "output": 8000 }
        }
      }
    }
  }
}

Hybrid — frontier planner, SCX.ai executor.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  },
  "model": "scx/coder",
  "small_model": "scx/coder",
  "agent": {
    "plan":  { "mode": "primary", "model": "anthropic/claude-opus-4-7" },
    "build": { "mode": "primary", "model": "scx/MiniMax-M2.7" }
  },
  "provider": {
    "anthropic": {
      "options": { "apiKey": "{env:ANTHROPIC_API_KEY}" },
      "models": {
        "claude-opus-4-7": {
          "name": "Claude Opus 4.7",
          "limit": { "context": 1000000, "output": 128000 }
        }
      }
    },
    "scx": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "SCX.ai",
      "options": {
        "baseURL": "https://api.scx.ai/v1",
        "apiKey": "{env:SCX_API_KEY}"
      },
      "models": {
        "MiniMax-M2.7": {
          "name": "MiniMax-M2.7",
          "reasoning": true,
          "tool_call": true,
          "limit": { "context": 191000, "output": 8000 }
        }
      }
    }
  }
}

Launch OpenCode in the folder:

bash
opencode

Press Tab to cycle between plan and build — the active model shows in the status bar.

The plan / build split

Pointing each agent at a different model gives you a clean architect‑and‑builder separation:

  • plan is read‑only by default — ideal for a reasoning model that reads the codebase, thinks, and writes a precise PLAN.md. Sovereign keeps this on scx/coder; hybrid hands it to a frontier model.
  • build has full edit and shell access — ideal for a fast, inexpensive model that grinds through the dozens of edits and test runs the plan calls for. Both postures run this on scx/MiniMax-M2.7.

The plan is the artifact that crosses the boundary: reviewable, editable, and re‑runnable. A typical loop:

  1. In plan (Tab), ask the agent to read the relevant files and write a step‑by‑step plan with a verification checklist — without changing any code.
  2. Review and tweak the plan. That's the point of having it as an artifact.
  3. Switch to build (Tab) and ask it to write the plan to PLAN.md and execute each step, reporting which checklist items pass as it goes.

Because both agents share one session, switching with Tab carries the full conversation across — the builder already has the plan in context. Re‑run build after editing PLAN.md, or swap the executor model, without rewriting anything.

Feed live docs to the planner with MCP

Models reason from training data that can lag behind a library's current API. Both configs already register the Context7 Model Context Protocol (MCP) server, so the planner can fetch current documentation and bake the resolved API straight into PLAN.md — the executor then works from facts, not guesses.

Restart OpenCode and run /mcps — context7 should appear with its resolve-library-id and query-docs tools. From the plan agent, ask it to look up the current API for a library through Context7 before writing the plan; the planner resolves today's docs and quotes them into PLAN.md. The build agent then executes without needing MCP access at all — the resolved API already lives in the plan.

Verify the connection

Before relying on OpenCode, confirm the key and endpoint directly:

bash
curl -sS "https://api.scx.ai/v1/chat/completions" \
  -H "Authorization: Bearer $SCX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MiniMax-M2.7","messages":[{"role":"user","content":"Say hi."}]}' \
  | jq '.choices[0].message.content'

A normal completion confirms the same credentials OpenCode uses are reaching SCX.ai.

Tips

  • Tab cycles the primary agents. Watch the status bar to confirm which model is active before prompting.
  • @plan / @build in a prompt delegates a single turn to the other agent without switching the active one.
  • Tell the executor to verify ("open the result and confirm…") — otherwise it tends to edit files and stop.
  • A per‑project opencode.json overrides the global config, so you can pin a SCX.ai model on one repo without touching others.

Common gotchas

  • "Model not found." OpenCode model IDs are provider/model — use scx/MiniMax-M2.7, never the bare MiniMax-M2.7. The bare ID only appears as a key inside provider.scx.models.
  • API key not picked up. {env:SCX_API_KEY} is resolved when OpenCode starts. Export the variable, then launch OpenCode from that same shell — not from a stale terminal pane.
  • Wrong endpoint. The base URL must end in /v1 (https://api.scx.ai/v1); the @ai-sdk/openai-compatible provider appends /chat/completions itself.