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

# Connect Claude Code

> Route Claude Code through the ForceAI gateway so every coding turn is guardrailed, budgeted and audited, without changing how developers work.

Claude Code speaks the Anthropic Messages API, so pointing it at ForceAI is a configuration change, not a code change: you set a base URL and a ForceAI key, and every turn flows through the gateway instead of straight to Anthropic. Guardrails, spend and audit apply automatically because it is ordinary gateway traffic

## What can and cannot be routed

The gateway only governs clients that speak the Anthropic API to a configurable endpoint. That is Claude Code and anything using the SDK, not the subscription surfaces

| Surface | Through the gateway? |
| - | - |
| Claude Code CLI (`claude` in a terminal) | Yes |
| Claude Code in an IDE extension (VS Code, JetBrains) | Yes |
| The **Code tab** inside the Claude Desktop app | Yes |
| The Claude Desktop **chat** app | No |
| `claude.ai` in a browser | No |

> [!NOTE]
>
> The desktop **chat** app and `claude.ai` web are the subscription product. They
> talk to Anthropic directly and have no configurable endpoint, so nothing can
> route them through ForceAI. Govern those through the Claude Enterprise admin
> console instead. Everything a developer runs as Claude Code can be routed.

## Point Claude Code at the gateway

Two settings matter. The base URL is the gateway **origin with no `/v1`** (Claude Code appends `/v1/messages` itself), and the credential is an ordinary ForceAI virtual key sent as a bearer token

**1. Choose where the config lives**

Use a shell `export` for a one-off session in a single terminal, or
`~/.claude/settings.json` to apply it to every Claude Code session on the
machine, including the desktop Code tab. See [Session vs persistent](#session-vs-persistent-config)

**2. Set the base URL, key and models**

Claude Code otherwise defaults to Sonnet/Opus model IDs. Pin it to a model the
gateway serves, or [register](#register-the-models) the IDs Claude Code sends

```bash Shell (one terminal) theme={null}
export ANTHROPIC_BASE_URL=https://your-gateway        # origin, NO /v1
export ANTHROPIC_AUTH_TOKEN=sk-your-forceai-key       # sent as Bearer
export ANTHROPIC_MODEL=claude-haiku-4-5               # a registered model
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5 # background tasks too
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
claude
```

```json ~/.claude/settings.json (persistent) theme={null}
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-gateway",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-forceai-key",
    "ANTHROPIC_MODEL": "claude-haiku-4-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}
```

**3. Run it**

Start `claude`. Every turn now posts to `your-gateway/v1/messages` and appears
in the dashboard under Logs with its guardrail trace

> [!WARNING]
>
> Setting only `ANTHROPIC_BASE_URL` with no credential variable leaves Claude Code
> on your saved claude.ai subscription login. The key (or `apiKeyHelper`) is what
> actually moves it onto the gateway, and it bills through the gateway's upstream,
> not your subscription seat.

## Session vs persistent config

A shell `export` is scoped to that one terminal: it affects only the `claude` you
launch there and its children. It never reaches the desktop app, which the OS
launches without your shell environment

`~/.claude/settings.json` is Claude Code's own config. It applies wherever Claude
Code runs, including the desktop Code tab. Settings are read at startup, so after
editing the file, restart the Claude Desktop app or start a new session to pick it
up. This file configures Claude Code only; it has no effect on the desktop chat app

## Register the models

The gateway fails closed on an unrecognized model and the error names the exact id
to register, so the loop is: run Claude Code once, read the rejected id, register
it. Add it in the dashboard under **Models + Endpoints -> Add Model**, or:

```bash theme={null}
curl -X POST "$FORCEAI_URL/model/new" \
  -H "Authorization: Bearer $FORCEAI_ADMIN_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model_name":"claude-sonnet-4-5-20250929",
       "forceai_params":{"model":"anthropic/claude-sonnet-4-5",
                          "api_key":"os.environ/ANTHROPIC_API_KEY"}}'
```

Pinning `ANTHROPIC_MODEL` and the `ANTHROPIC_DEFAULT_*_MODEL` variables to already
registered names is the quick alternative. Note that background tasks use the
Haiku model, so register (or pin) it even if nobody selects it

## Verify it is governed

```bash theme={null}
curl -s -o /dev/null -w '%{http_code}\n' \
  "$FORCEAI_URL/v1/messages" \
  -H "Authorization: Bearer $FORCEAI_KEY" \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  -d '{"model":"claude-haiku-4-5","max_tokens":10,
       "messages":[{"role":"user","content":"hi"}]}'
```

A `200` confirms the gateway serves the Anthropic endpoint for the model. Then run
Claude Code and open the request in the dashboard under Logs. The guardrail trace
on that row is the proof the session is governed rather than merely proxied

> [!NOTE]
>
> A `pre_call` guardrail sits in the latency path of every turn. An interactive
> coding tool feels per-turn latency far more than a batch caller does, so measure
> it on a real session before a wide rollout.

## Roll it out to a team

For a fleet, enforce the gateway centrally with Claude Code **managed settings**
rather than relying on each developer's shell or user settings. An org owner pushes
the same `env` block from the claude.ai admin console (server-managed settings, no
device management) or through MDM, and `allowedProviders: ["customEndpoint"]`
makes the pinned base URL mandatory so a developer cannot point Claude Code
elsewhere. See the enterprise rollout runbook in the repository for the full
pattern, including the provisioning of per-developer keys and the direct-to-Anthropic
side channels to close


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.