Docs

Connect

Claude Code

Connect Claude Code to Arena.

Before you begin

  • Claude Code installed on macOS, Linux or WSL2. Native Windows works with the manual setup.
  • An Arena account with access to the Keys page.

Set up

Choose how to set up
  1. 1. Run the setup script

    Run this in a terminal. It finds Claude Code, opens your browser to approve the connection, creates a key, and saves your connection settings and model menu.

    curl -fsSL <portal-url>/setup.sh | bash
  2. 2. Check it works

    Restart Claude Code if it was open, then start it:

    claude

    Type /model. You should see your Arena models, with Arena Router listed as Arena Coding Router. Send a short prompt, and the request appears on Usage.

    If the prompt fails, read the tool's error and check your Arena key and base URL in the saved configuration.

  1. 1. Create an API key

    Create a key on the Keys page. You can only copy it once.

  2. 2. Save Claude Code settings

    Paste this into ~/.claude/settings.json, replace the token placeholder with your Arena key, and keep your other settings. Then restart Claude Code. The model menu (modelPicker) requires Claude Code 2.1.242 or later; older versions ignore it and keep the built-in menu.

    Router example:

    Claude Code settings. Paste into a new settings file, or merge env and replace modelPicker with this selection.

    ~/.claude/settings.json
    {
      "env": {
        "ANTHROPIC_BASE_URL": "https://api.arena.ai",
        "ANTHROPIC_AUTH_TOKEN": "<your-arena-key>",
        "ANTHROPIC_MODEL": "coding-router-preview",
        "ANTHROPIC_DEFAULT_MODEL": "coding-router-preview",
        "ANTHROPIC_SMALL_FAST_MODEL": "coding-router-preview",
        "CLAUDE_CODE_SUBAGENT_MODEL": "coding-router-preview",
        "CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT": "1",
        "CLAUDE_CODE_MODEL_CAPABILITIES": "coding-router-preview=-effort"
      },
      "modelPicker": {
        "replaceBuiltInOptions": true,
        "options": [
          {
            "model": "coding-router-preview",
            "label": "Arena Coding Router",
            "description": "Arena Coding Router"
          }
        ]
      }
    }

    Sign in to generate this for your workspace's models.

  3. 3. Check it works

    Restart Claude Code if it was open, then start it:

    claude

    Type /model. You should see your Arena models, with Arena Router listed as Arena Coding Router. Send a short prompt, and the request appears on Usage.

    If the prompt fails, read the tool's error and check your Arena key and base URL in the saved configuration.

Optional: use the full 1M-token context

Claude Code versions before 2.1.323 assume a 200K-token context for Arena model IDs. Arena Router accepts up to 1,000,000 tokens. To use the full window on any version, add this to ~/.claude/settings.json (merge it into your existing env block), then restart Claude Code:

~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "1000000"
  }
}

Claude Code then measures your conversation against the full window, so it shows accurate context usage and summarizes older turns only as you approach 1M tokens. If you mostly use a direct model with a smaller window, use that model's context length from the Models page instead. Claude models that Claude Code recognizes keep their own window and ignore this setting.

Tips

  • Switch and update models. Type /model in a session to switch. To get new models or change your default, see Switching models.
  • Undo the setup. See Uninstall in the Quickstart.

Troubleshooting

Arena models are missing from /model
Restart any session that was open during setup; open sessions keep their old connection. If you set it up by hand, update Claude Code, since older versions ignore the Arena model menu.
Claude Code still uses another model or provider
Shell or launcher variables such as ANTHROPIC_DEFAULT_*_MODEL or CLAUDE_CODE_USE_* take priority over your settings. Unset them and restart.
403 organization_model_restricted
The model is not enabled for your workspace. Pick another model in /model, or rerun the setup script and choose update models.
403 organization_client_restricted
Your workspace only allows approved apps. Use Claude Code interactively in a terminal or in Claude Desktop; print mode, the Agent SDK and the VS Code extension are blocked for router requests. Workspaces with API client access can use them.
You use CLAUDE_CONFIG_DIR
Save the settings file in that directory instead of ~/.claude.

Next steps