> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corvex.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Claude Code with Corvex

> Run Claude Code against a Corvex-served model with an isolated config directory launcher.

Claude Code speaks the Anthropic API, and Corvex exposes an Anthropic-compatible
endpoint. You can point Claude Code at a Corvex model by setting a base URL, your
API key, and the model to use. The launcher below wires those in for a single run
and isolates the session in its own config directory (`~/.claude-corvex`) via
`CLAUDE_CONFIG_DIR`. Your normal Claude credentials, sessions, and settings stay
untouched. You can run Claude Code through Corvex alongside your normal Claude
Code sessions at the same time.

## Prerequisites

* A Corvex API key (`sk-corvex-...`) from the Token Factory dashboard. See
  [Authentication](/getting-started/authentication).
* A model name from the [Models](/models/overview) catalog (this guide uses
  `zai-org/GLM-5.2-FP8` as the example).
* [Claude Code](https://docs.claude.com/en/docs/claude-code) installed and `jq` available.

## Context length

Claude Code doesn't auto-detect the context window of a model reached over a
custom endpoint. It caps the usable window at **200K** tokens. Both Corvex
models have a larger native window than that, but over this integration the
session is bounded at 200K regardless. Configure compaction to that ceiling:

* **`CLAUDE_CODE_AUTO_COMPACT_WINDOW`**: set this to `200000`, the window
  Claude Code actually enforces here. Setting it to the model's larger native
  window would put the compaction trigger past the limit the session hits, so
  compaction would never fire and the session would fail on a full context
  instead.
* **`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`**: percentage (1-100) of that window at
  which compaction triggers, e.g. `90` to compact with \~10% headroom.

| Model                       | Native window  | Usable via Claude Code | `CLAUDE_CODE_AUTO_COMPACT_WINDOW` |
| --------------------------- | -------------- | ---------------------- | --------------------------------- |
| `zai-org/GLM-5.2-FP8`       | 393,216 (384K) | 200,000                | `200000`                          |
| `moonshotai/Kimi-K2.7-Code` | 262,144 (256K) | 200,000                | `200000`                          |

Confirm with `/context` in a session. To use a model's full native window, call
the API directly; see the [Quickstart](/getting-started/quickstart).

<Steps>
  <Step title="Store your key and endpoint in a private env file">
    Replace `sk-corvex-...` with your key from the dashboard.

    ```bash theme={null}
    mkdir -p ~/.corvex
    chmod 700 ~/.corvex

    cat > ~/.corvex/claude-code.env <<'EOF'
    export CORVEX_API_KEY="sk-corvex-..."
    export CORVEX_BASE_URL="https://api.tokenfactory.corvex.cloud"
    export CORVEX_CLAUDE_MODEL="zai-org/GLM-5.2-FP8"
    export CLAUDE_CODE_AUTO_COMPACT_WINDOW="200000"   # the window Claude Code enforces (see table above)
    export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE="90"
    EOF

    chmod 600 ~/.corvex/claude-code.env
    ```
  </Step>

  <Step title="Create the launcher">
    This `claude-corvex` launcher points Claude Code at Corvex for one session by
    isolating it in its own config directory (`~/.claude-corvex`) via
    `CLAUDE_CONFIG_DIR`. It sources your env file, exports the Corvex endpoint and
    model, and passes arguments through to `claude`. Your normal Claude credentials
    are never touched.

    The script installs to `~/.local/bin` so you can invoke it as `claude-corvex`
    from any directory. That directory is on `PATH` by default on most Linux
    distributions; on macOS, add `export PATH="${HOME}/.local/bin:${PATH}"` to your
    shell profile (e.g. `~/.zshrc`) and restart your shell.

    ```bash theme={null}
    mkdir -p ~/.local/bin
    cat > ~/.local/bin/claude-corvex <<'EOF'
    #!/usr/bin/env bash
    set -euo pipefail

    CLAUDE_CONFIG_DIR="${HOME}/.claude-corvex"
    ENV_FILE="${HOME}/.corvex/claude-code.env"

    if [[ ! -f "${ENV_FILE}" ]]; then
      echo "[claude-corvex] missing ${ENV_FILE}" >&2
      exit 1
    fi

    set -a
    # shellcheck disable=SC1090
    source "${ENV_FILE}"
    set +a

    mkdir -p "${CLAUDE_CONFIG_DIR}"

    # Customizations (plugins, settings) and MCP servers are NOT mirrored on launch.
    # Run claude-corvex-migrate to carry them over (see the optional Step below).

    MODEL="${CORVEX_CLAUDE_MODEL}"

    export CLAUDE_CONFIG_DIR
    export ANTHROPIC_BASE_URL="${CORVEX_BASE_URL}"
    export ANTHROPIC_AUTH_TOKEN="${CORVEX_API_KEY}"
    export ANTHROPIC_MODEL="${MODEL}"
    export ANTHROPIC_DEFAULT_SONNET_MODEL="${MODEL}"
    export ANTHROPIC_DEFAULT_OPUS_MODEL="${MODEL}"
    export ANTHROPIC_DEFAULT_HAIKU_MODEL="${MODEL}"
    export CLAUDE_CODE_SUBAGENT_MODEL="${MODEL}"
    export CLAUDE_CODE_AUTO_COMPACT_WINDOW="${CLAUDE_CODE_AUTO_COMPACT_WINDOW:-}"
    export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE="${CLAUDE_AUTOCOMPACT_PCT_OVERRIDE:-90}"

    echo "[claude-corvex] ${ANTHROPIC_BASE_URL}" >&2
    echo "[claude-corvex] model: ${MODEL}" >&2

    claude --model "${MODEL}" "$@"
    EOF

    chmod 700 ~/.local/bin/claude-corvex
    ```
  </Step>

  <Step title="Smoke-test the endpoint">
    Confirm your key and endpoint work before launching Claude Code.

    ```bash theme={null}
    source ~/.corvex/claude-code.env

    curl -sS "${CORVEX_BASE_URL}/v1/models" \
      -H "Authorization: Bearer ${CORVEX_API_KEY}" \
      | jq .
    ```
  </Step>

  <Step title="Run Claude Code through Corvex">
    ```bash theme={null}
    cd /path/to/your/repo
    claude-corvex
    ```

    Inside Claude Code, verify it is pointed at Corvex:

    ```text theme={null}
    /status
    /model
    ```
  </Step>

  <Step title="Carry over your plugins and MCP servers (optional)">
    The launcher does not mirror your customizations on launch, so the Corvex
    profile starts clean. Run this `claude-corvex-migrate` script to carry your
    plugins, settings, `CLAUDE.md`, and MCP servers from your normal Claude profile
    into `~/.claude-corvex`. Run it once before launching, or again after changing
    your main Claude config. It is safe to re-run and best-effort: a missing tool or
    failed step warns and continues, and the launcher works regardless.

    The first part copies named paths from `~/.claude/` via an rsync include-list
    (only those paths copy, so credentials and runtime state never leak across). It
    needs `rsync`, skipped with a warning if absent. The second part merges only the
    `mcpServers` key from `~/.claude.json` into the Corvex profile. It needs `jq`.
    The first run may be slow if your plugin tree is large.

    ```bash theme={null}
    cat > ~/.local/bin/claude-corvex-migrate <<'EOF'
    #!/usr/bin/env bash
    # Carry customizations and MCP servers from your normal Claude profile (~/.claude,
    # ~/.claude.json) into the Corvex profile (~/.claude-corvex). Run once before
    # launching claude-corvex, or again after changing your main Claude config. Safe to
    # re-run; best-effort (a missing tool or failed step warns and continues).
    #
    # Step 1 copies named paths from ~/.claude/ via an rsync include-list (only those
    # paths copy, so credentials and runtime state never leak across). Step 2 merges
    # only the mcpServers key from ~/.claude.json (where MCP servers actually live,
    # NOT under ~/.claude/), overwriting the Corvex profile's mcpServers to mirror the
    # main config and leaving all other Corvex runtime state intact.
    set -euo pipefail

    DEFAULT_CLAUDE_CONFIG_DIR="${HOME}/.claude"
    CLAUDE_CONFIG_DIR="${HOME}/.claude-corvex"

    mkdir -p "${CLAUDE_CONFIG_DIR}"

    # 1) Customizations under ~/.claude/ (plugins, settings, skills, ...).
    if command -v rsync >/dev/null 2>&1; then
      echo "[claude-corvex] mirroring ~/.claude customizations -> ${CLAUDE_CONFIG_DIR} (first run may take a while)..." >&2
      if rsync -a --no-owner --no-group \
        --include 'settings.json' \
        --include 'CLAUDE.md' \
        --include 'plugins/***' \
        --include 'commands/***' \
        --include 'agents/***' \
        --include 'output-styles/***' \
        --include 'skills/***' \
        --include 'keybindings.json' \
        --include '.mcp.json' \
        --exclude '*' \
        "${DEFAULT_CLAUDE_CONFIG_DIR}/" "${CLAUDE_CONFIG_DIR}/"; then
        echo "[claude-corvex] mirrored ~/.claude customizations -> ${CLAUDE_CONFIG_DIR}" >&2
      else
        echo "[claude-corvex] rsync failed; skipped customizations" >&2
      fi
    else
      echo "[claude-corvex] rsync not found; skipped customizations" >&2
    fi

    # 2) MCP servers (user scope) from ~/.claude.json. Overwrite mcpServers to mirror
    #    the main config; preserve all other keys in the Corvex .claude.json.
    if ! command -v jq >/dev/null 2>&1; then
      echo "[claude-corvex] jq not found; skipped MCP (install jq to carry MCP servers)" >&2
    elif [[ ! -f "${HOME}/.claude.json" ]]; then
      echo "[claude-corvex] no ~/.claude.json; skipped MCP (nothing to merge)" >&2
    else
      dst="${CLAUDE_CONFIG_DIR}/.claude.json"
      tmp="${dst}.tmp"
      [[ -f "${dst}" ]] || echo '{}' > "${dst}"
      echo "[claude-corvex] merging mcpServers from ~/.claude.json -> ${dst}..." >&2
      if jq --slurpfile s "${HOME}/.claude.json" \
        '.mcpServers = ($s[0].mcpServers // {})' "${dst}" > "${tmp}"; then
        mv -f "${tmp}" "${dst}"
        echo "[claude-corvex] merged mcpServers -> ${dst}" >&2
      else
        rm -f "${tmp}"
        echo "[claude-corvex] mcpServers merge failed; ${dst} left unchanged" >&2
      fi
    fi
    EOF

    chmod 700 ~/.local/bin/claude-corvex-migrate
    ```

    Run it:

    ```bash theme={null}
    claude-corvex-migrate
    ```
  </Step>
</Steps>

## Subcommands

The launcher passes arguments straight through to `claude` and exports
`CLAUDE_CONFIG_DIR`, so `mcp`, `plugin`, `config`, and other subcommands target
`~/.claude-corvex` automatically.

```bash theme={null}
claude-corvex mcp list
claude-corvex mcp add <name> -s user -e KEY=val -- <command>
claude-corvex plugin ...
claude-corvex config ...
```

* `claude mcp add` run via this launcher writes to the **Corvex** profile
  (`~/.claude-corvex/.claude.json`), not your normal one. That is the isolation
  working as intended.
* Use `-s user` (or `local`) for personal config. `-s project` writes a
  `.mcp.json` into the current project dir, which is shared across both profiles.

## Known caveats

* **Isolation.** The launcher sets `CLAUDE_CONFIG_DIR` to `~/.claude-corvex`,
  giving the Corvex profile its own sessions, projects, history, and settings.
  Your normal Claude credentials are never touched, so normal Claude stays logged
  in unconditionally. You can run both profiles at the same time.
* **Customizations not mirrored.** The launcher does not copy your plugins,
  settings, `CLAUDE.md`, or MCP servers into the Corvex profile on launch.
  Without running `claude-corvex-migrate` (the optional Step above), the Corvex
  profile starts with no customizations. Run migrate once before launching, or
  again after changing your main Claude config.
* **Prompt caching.** The Anthropic Messages surface accepts `cache_control`
  annotations, but Corvex does not implement prompt caching. The annotations are
  accepted so Claude Code and Anthropic SDK clients work unchanged; every
  response reports zero cache usage. See
  [Errors: Prompt caching](/reference/errors#prompt-caching-cache_control) for
  details.
* **Model capabilities.** Not every Corvex model supports every Anthropic
  feature (for example, some are text-only). If Claude Code sends a request the
  model cannot fulfill, the gateway returns a structured error. Pick a model
  whose capability list matches your workflow from the
  [Models](/models/overview) page.

<Note>
  If you switch models, update `CORVEX_CLAUDE_MODEL`. Leave
  `CLAUDE_CODE_AUTO_COMPACT_WINDOW` at `200000`: it is the ceiling Claude Code
  enforces over a custom endpoint, not a per-model value.
</Note>