Using Aegis With Agents

Step 1: Install OpenCode CLI, Desktop, Or Both

• CLI on macOS, Linux, or WSL: run the official installer below.
• Desktop on macOS: use Homebrew below or download the Apple Silicon or Intel build from opencode.ai/download.
• Desktop on Windows: download the x64 installer from opencode.ai/download.
• Desktop on Linux: download the `.deb` or `.rpm` package from opencode.ai/download.
• Windows CLI users should follow the OpenCode Windows and WSL guide.

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

brew install --cask opencode-desktop

Step 2: Create Your Aegis API Key

• Sign in to Aegis.
• Open Dashboard > API Keys.
• Enter a clear name such as `OpenCode`.
• Choose the default service tier and, if needed, set a monthly budget limit.
• Click `Generate Key`, then copy the `aegis_...` value immediately.
• Store it securely until you paste it into the global OpenCode configuration in Step 3.

Step 3: Configure The Shared Aegis Provider

• Copy the configuration below into `~/.config/opencode/opencode.jsonc`.
• Replace `your_aegis_api_key_here` with the full key from Step 2.
• Keep the provider ID as `aegis`; the default model reference `aegis/glm-5.2` depends on that exact ID.
• Keep the base URL as https://api.aegisrouter.com/v1.
• Save and exit (`Ctrl-O`, `Enter`, `Ctrl-X` in nano).
• If OpenCode Desktop is already running, fully quit and reopen it after saving.

mkdir -p ~/.config/opencode
nano ~/.config/opencode/opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "model": "aegis/glm-5.2",
  "provider": {
    "aegis": {
      "name": "Aegis",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://api.aegisrouter.com/v1",
        "apiKey": "your_aegis_api_key_here"
      },
      "models": {
        "glm-5.2": {
          "name": "GLM-5.2",
          "limit": {
            "context": 1048560,
            "output": 128072
          }
        }
      }
    }
  }
}

Step 4: Launch And Verify OpenCode CLI

• Run `/init` once to analyze the project and create `AGENTS.md`.
• Run `/models` and select `Aegis > GLM-5.2` (`aegis/glm-5.2`).
• Send a short prompt and confirm OpenCode returns a response.

cd /path/to/project
opencode

# In the OpenCode TUI:
#   /init
#   /models

Step 5: Launch And Verify OpenCode Desktop

• Fully quit and reopen Desktop if it was running while you edited `opencode.jsonc`.
• Open or select the project folder you want to work in.
• Open the model picker and select `Aegis > GLM-5.2` (`aegis/glm-5.2`).
• Start a new session and send a short prompt.
• If you installed both clients, you do not need to paste the Aegis key a second time.

Step 6: Confirm Usage And Troubleshoot

• Missing provider: confirm the global config is at `~/.config/opencode/opencode.jsonc` and the provider ID is exactly `aegis`.
• Authentication error: replace `your_aegis_api_key_here` with the real key copied in Step 2.
• Missing model: confirm `glm-5.2` exists under `provider.aegis.models`, then reopen `/models` or restart Desktop.
• Wrong model in one project: check that project's `opencode.json` or `opencode.jsonc` for an override.
• Desktop still shows old settings: fully quit the application, reopen it, and load the project again.
• No Analytics event: confirm the endpoint is exactly https://api.aegisrouter.com/v1, send another prompt, and refresh Analytics.

Step 1: Download Claude Code Router Desktop

• macOS Apple Silicon: choose the `arm64` DMG.
• macOS Intel: choose the `x64` DMG.
• Windows: choose the `.exe` installer.
• Linux: choose the `.AppImage` file.
• Install the app, launch it, and leave it running.

Step 2: Download Claude Code

• Desktop: open claude.com/download, download the app for your OS, and install it.
• CLI: run the native installer for your operating system below, then verify the installation with `claude --version`.
• If you want to use Claude Code from both the desktop app and your terminal, install both.

curl -fsSL https://claude.ai/install.sh | bash
claude --version

irm https://claude.ai/install.ps1 | iex
claude --version

Step 3: Create An Aegis API Key

• Enter a clear key name, such as `Claude Code`.
• Choose the default service tier you want this key to use.
• Optionally set a monthly budget limit.
• Click `Generate Key`, copy the full key, and store it securely.

Step 4: Configure The Aegis Provider

• Name: `aegis` (or another short, clear provider name).
• API endpoint: https://api.aegisrouter.com/v1.
• Click `Next step`, select `API key`, and paste the `aegis_...` key from Step 3.
• Do not select `Credential pool` unless you intentionally want CCR to rotate between multiple Aegis keys.

Step 5: Pick Models And Verify The Connection

• If Provider models loads normally, select `glm-5.2` or any other supported model you want to expose.
• If it says `No provider models`, click `Custom model`, enter `glm-5.2` exactly, and confirm it. You do not need to wait for automatic discovery.
• On `Verify connection`, wait for the protocol check, then click `Check Connection` to send a small real request.
• Continue only after the connection succeeds.

Step 6: Connect The Claude Code Profile

• Agent: `Claude Code`.
• Profile name: `Claude Code`.
• Effect scope: `System default`.
• Entry mode: `CLI & APP` when both are installed; otherwise select the entry mode you use.
• Default model: `aegis/glm-5.2`.
• Fable, Opus, Sonnet, and Haiku model aliases are optional. Leave them on `Keep Claude Code default` unless you want explicit per-alias routing.
• Click `Next step` and make sure Provider and Profile both show a green check on `Let's start`.

Step 7: Start CCR And Test Claude Code

• Confirm the Claude Code profile is enabled under `Agent Profiles`.
• Send a short prompt, then open Aegis Dashboard > Analytics and confirm the request appears.
• `EADDRINUSE: address already in use 127.0.0.1:3456` means another CCR process already owns the port. Quit the duplicate Desktop or CLI instance, then start one CCR instance.
• `400 All target providers failed` is a CCR wrapper error. Open `Logs` and inspect the target attempt, then recheck the `/v1` endpoint, Aegis key, selected model ID, and detected protocol.
• If only the CLI works, edit the profile and change Effect scope to `System default` and Entry mode to `CLI & APP`, then fully restart Claude.

curl http://127.0.0.1:3456/

# Then launch Claude Code and send a short test prompt.