Coding agent setup

Connect your coding agent.

Pick the tool your team already uses. OpenCode can read your Model Oracle AI key from an environment variable referenced by its config. Cursor can use Model Oracle AI when your Cursor build exposes an OpenAI-compatible base URL override.

1. Get your endpoint and key

Use the hosted Model Oracle AI API endpoint, or replace it with your team's private deployment URL.

https://api.modeloracle.com/api/v1

Use your Model Oracle AI key in the coding agent. You can use managed access or add encrypted provider keys in the dashboard. Provider keys stay inside Model Oracle AI and are not configured in Cursor, Claude Code, Codex, or OpenCode.

2. Pick your coding agent

Default path

OpenCode

The easiest setup is to run /connect in OpenCode. Search for and select Model Oracle AI, then paste your Model Oracle AI API key. OpenCode stores the credential in ~/.local/share/opencode/auth.json. Use auto for most work so Model Oracle AI can choose the best available model for the request.

Manual fallback: if you cannot use /connect, set MODEL_ORACLE_API_KEY in your shell and add the provider config below. You do not need to run /connect when using this fallback. Put the provider entry in ~/.config/opencode/opencode.json to make it available to every project, or in opencode.json at a project root for that project only. OpenCode merges both files, with the project file taking precedence. Adjust the baseURL and keep only the logical models your team wants developers to select.

export MODEL_ORACLE_API_KEY="your-model-oracle-api-key"

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "model-oracle-ai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Model Oracle AI",
      "options": {
        "baseURL": "https://api.modeloracle.com/api/v1",
        "apiKey": "{env:MODEL_ORACLE_API_KEY}"
      },
      "models": {
        "auto": { "name": "Auto (Decision Engine)" },
        "claude-fable-5": { "name": "Claude Fable 5" },
        "claude-haiku-4.5": { "name": "Claude Haiku 4.5" },
        "claude-opus-4.8": { "name": "Claude Opus 4.8" },
        "claude-opus-5": { "name": "Claude Opus 5" },
        "claude-sonnet-5": { "name": "Claude Sonnet 5" },
        "deepseek-v4-pro": { "name": "DeepSeek V4 Pro" },
        "glm-5.2": { "name": "GLM 5.2" },
        "gpt-4.1": { "name": "GPT-4.1" },
        "gpt-4.1-mini": { "name": "GPT-4.1 Mini" },
        "gpt-5": { "name": "GPT-5" },
        "gpt-5.4": { "name": "GPT-5.4" },
        "gpt-5.4-mini": { "name": "GPT-5.4 Mini" },
        "gpt-5.4-nano": { "name": "GPT-5.4 Nano" },
        "gpt-5.5": { "name": "GPT-5.5" },
        "gpt-5.6-luna": { "name": "GPT-5.6 Luna" },
        "gpt-5.6-sol": { "name": "GPT-5.6 Sol" },
        "gpt-5.6-terra": { "name": "GPT-5.6 Terra" },
        "kimi-k3": { "name": "Kimi K3" },
        "kimi-k2.7-code": { "name": "Kimi K2.7 Code" },
        "o4-mini": { "name": "OpenAI o4-mini" }
      }
    }
  }
}

Stable logical model names such as kimi-k3 or deepseek-v4-pro are available when a workload needs a fixed model family.

Logical model IDs are case-sensitive. Do not copy provider namespaces or upstream model IDs into OpenCode. Model Oracle AI links each logical model to its provider-specific models and manages provider fallback behind the scenes.

Choose either the recommended /connect flow or the manual config fallback—you do not need to configure the API key both ways.

Cursor

In Cursor, open Settings and look for the model provider controls for using your own OpenAI-compatible API key. Paste your Model Oracle AI key as the OpenAI API key, then set the OpenAI-compatible base URL to:

https://api.modeloracle.com/api/v1

Use auto as the model when Cursor allows custom model names. Use a logical model ID only when the workload needs a fixed model family.

If your Cursor version does not expose a base URL override for OpenAI-compatible providers, Cursor cannot point at Model Oracle AI directly yet. Use OpenCode or Codex for direct Model Oracle AI traffic until that control is available in your Cursor build.

You can verify the same key and endpoint outside Cursor with this streaming request:

curl https://api.modeloracle.com/api/v1/chat/completions \
  -H "Authorization: Bearer $MODEL_ORACLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Reply with ok."}],
    "stream": true
  }'

Codex

Codex supports user-level custom model providers in ~/.codex/config.toml. Add a provider that points at Model Oracle AI and set the model to auto or a logical model exposed by your control plane.

model = "auto"
model_provider = "model-oracle-ai"

[model_providers.model-oracle-ai]
name = "Model Oracle AI"
base_url = "https://api.modeloracle.com/api/v1"
env_key = "MODEL_ORACLE_API_KEY"

Set MODEL_ORACLE_API_KEY only if your Model Oracle AI instance requires a local control-plane key. Keep provider keys in Model Oracle AI, not in Codex. This uses the OpenAI-compatible endpoint exposed by the current backend.

Claude Code

Claude Code talks to an Anthropic-compatible Messages API. Point it at the Model Oracle AI Messages endpoint and use your Model Oracle AI key as the Anthropic auth token.

ANTHROPIC_BASE_URL=https://api.modeloracle.com/api/v1
ANTHROPIC_AUTH_TOKEN=$MODEL_ORACLE_API_KEY

Use an Anthropic-compatible logical model such as claude-opus-5, or use auto to let Model Oracle AI choose from active Anthropic models.

3. Send a test prompt

Ask the agent to inspect a repository or make a small change. After the first request goes through Model Oracle AI, the dashboard will show request count, token usage, estimated spend, latency, errors, prompt details, completion details, provider, and model.

Control your auto session

Keep your client model set to auto, then send an @oracle command as the complete message when you want to inspect or temporarily control Model Oracle AI's model selection. Commands work with both the OpenAI-compatible and Anthropic-compatible setup paths, do not reach an end model, and use zero inference tokens.

@oracle status
@oracle use economy
@oracle use balanced
@oracle use premium
@oracle use kimi-k3
@oracle use auto
@oracle help

Economy, balanced, and premium select exactly that tier. A logical model ID is case-sensitive and pins that model while Model Oracle AI continues to manage provider fallback. Send @oracle use auto to return to normal Model Intelligence.

Session overrides expire after 24 hours of inactivity. If a client has not supplied enough session context yet, Model Oracle AI holds the override for five minutes and attaches it to the next auto request made with that API key.

Reasoning controls

Model Oracle AI accepts the top-level reasoning_effort field for reasoning-capable logical models and forwards or translates it for the selected upstream provider.

GPT-5.6 Luna, Sol, and Terra

Supported effort values: nonelowmediumhighxhighmax

Kimi K3

Kimi K3 always reasons. Supported effort values: lowhighmax

curl https://api.modeloracle.com/api/v1/chat/completions \
  -H "Authorization: Bearer $MODEL_ORACLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [{"role": "user", "content": "Plan a safe refactor."}],
    "reasoning_effort": "high"
  }'