Appearance
Claude Code
Claude Code is Anthropic's command-line coding agent. It takes a custom base URL and credential, so it can send every request through Corveil.
This page covers two setups:
- One machine: Direct or Passthrough mode, set in your shell or your own settings file.
- A fleet: Roll out to a fleet. Your device management tool pushes Corveil's address to every machine, and each person adds their own Corveil key.
Prerequisites
- A running Corveil instance (see deployment options)
- A Corveil virtual API key (
sk-citadel-...). See Getting a key. - Claude Code installed
Getting a key
If your organization role can create API keys (Member, Gateway user, Admin, Owner, or a custom role with Manage own API keys), create one in the dashboard, or run corveil login, which saves a key to its config profile.
Viewer, Billing admin, and the budget roles can't create keys. corveil login stops with "Your role in … can't create API keys" and mints nothing. Ask an admin to give you a key (see Give each person a key for the ways they can), then put it in ANTHROPIC_API_KEY below, or ask for a role that can create keys.
Mode
Direct and Passthrough modes supported. In Direct mode Claude Code's credential is a Corveil key. In Passthrough mode it keeps its own Anthropic credential and adds a Corveil key in a header.
Both modes send Claude Code's traffic to Anthropic. If the bill must stay on your AWS account instead, run Claude Code in Bedrock mode against Corveil: see Claude Code on Amazon Bedrock.
Option A: Direct Mode
Your credential is a Corveil virtual key. Corveil authenticates the request and forwards it upstream using its own provider credentials.
bash
export ANTHROPIC_BASE_URL="https://your-corveil-host"
export ANTHROPIC_API_KEY="sk-citadel-your-key-here"Or configure via settings.json (project .claude/settings.local.json or global ~/.claude/settings.json; never the shared project .claude/settings.json, which is committed with the repository):
json
{
"env": {
"ANTHROPIC_BASE_URL": "https://your-corveil-host",
"ANTHROPIC_API_KEY": "sk-citadel-your-key-here"
}
}ANTHROPIC_AUTH_TOKEN works in place of ANTHROPIC_API_KEY. Claude Code sends ANTHROPIC_API_KEY in the x-api-key header and asks you once to approve it, and sends ANTHROPIC_AUTH_TOKEN as Authorization: Bearer with no prompt. Corveil reads the key from either header.
Option B: Passthrough Mode
Your own Anthropic API key or OAuth token is sent directly to Anthropic. A separate x-citadel-api-key header authenticates with Corveil for tracking and guardrails.
If you use the corveil CLI, let it set the variables from your login profile, so the key never lands in your dotfiles:
bash
claude login # once: your Claude subscription
corveil login # once: your Corveil key
eval "$(corveil env claude-code)" && claudecorveil env claude-code prints the exports below, plus unset ANTHROPIC_API_KEY (if that variable is set, Claude Code sends it instead of your subscription's token and Corveil rejects the request). Add --profile <name> to use another login profile, --shell fish for fish, --shell powershell for PowerShell, --mode direct for Option A, or --unset to stop routing through Corveil. If the CLI isn't logged in, it prints nothing and exits non-zero. The output contains your key, so evaluate it rather than saving it to a file.
On Windows, in PowerShell:
powershell
claude login
corveil login
corveil env claude-code --shell powershell | Out-String | Invoke-Expression
claudeWithout the CLI, set them by hand:
bash
export ANTHROPIC_BASE_URL="https://your-corveil-host"
export ANTHROPIC_CUSTOM_HEADERS="x-citadel-api-key: sk-citadel-your-key-here"or in PowerShell:
powershell
$env:ANTHROPIC_BASE_URL = "https://your-corveil-host"
$env:ANTHROPIC_CUSTOM_HEADERS = "x-citadel-api-key: sk-citadel-your-key-here"Passthrough is a per-machine setup. For a fleet, use the rollout below.
Launch and Verify
bash
claude- Run
/status. The Status tab shows anAnthropic base URLline with your Corveil address. Without that line, the base URL didn't reach Claude Code. - Send a prompt. A normal answer means requests are flowing through Corveil.
- In Corveil, open Monitoring → Logs. Each turn is a row under your key, with its model, tokens and cost.
Roll out to a fleet
Your device management tool pushes the shared settings to every machine as Claude Code managed settings, and each person adds their own Corveil key. Don't hand out one shared key: all spend and every request would be on that one key, and you couldn't cut off one person without cutting off everyone.
A managed value wins over the person's shell and their own settings files, so people can't point Claude Code somewhere else. The same holds for a mistake: a wrong managed address stops Claude Code for every engineer at once. Test on one machine before you deploy.
Which setup do I need?
Claude Code can reach Corveil through the Anthropic API or through Amazon Bedrock. Pick one per machine:
| Anthropic API through Corveil | Amazon Bedrock through Corveil | |
|---|---|---|
| Who bills the tokens | Anthropic, on your organization's Anthropic key stored in Corveil | AWS, on your organization's AWS account |
| Setup in Corveil | An Anthropic provider credential | The Bedrock prerequisites: an AWS credential and the inference profiles enabled in Catalog |
| Each person's key goes in | ANTHROPIC_AUTH_TOKEN | AWS_BEARER_TOKEN_BEDROCK |
| Output guardrails | Applied | Logged only; output is not redacted |
Use Bedrock when the bill must stay on your AWS account, or when your engineers already run Claude Code on Bedrock. To check what a machine uses today, run /status in Claude Code: Bedrock shows API provider: Amazon Bedrock. Otherwise use the Anthropic API path: it needs no AWS setup.
1. Install Claude Code
Install Claude Code with your device management tool: the Homebrew cask claude-code on macOS, the WinGet package Anthropic.ClaudeCode on Windows, or a Linux package. Anthropic's setup guide lists every method, and its MDM examples have Jamf, Kandji, Intune and Group Policy templates.
allowedProviders needs Claude Code v2.1.285 or later, and wslInheritsWindowsSettings v2.1.282 or later. Earlier versions don't enforce them. To keep older versions from starting, add requiredMinimumVersion to the managed settings.
2. Download your organization's managed settings
On People & Access → Organization, choose Get Claude Code profile. Pick Anthropic API or Amazon Bedrock, then download the file for your device management tool. Your Corveil address is already filled in.
| File | Where it goes |
|---|---|
managed-settings.json | Any OS. /Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux and WSL, or C:\Program Files\ClaudeCode\ on Windows |
corveil-claude-code.mobileconfig | macOS configuration profile for Jamf Pro, Kandji or Intune. Device scope, preference domain com.anthropic.claudecode |
com.anthropic.claudecode.plist | macOS custom settings payload in Jamf Pro or Kandji. Enter com.anthropic.claudecode as the preference domain |
corveil-claude-code.reg | Windows. The Settings value (REG_SZ) under HKLM\SOFTWARE\Policies\ClaudeCode. Import it, or put the same JSON in that value with Group Policy or Intune |
The Bedrock files have -bedrock in their names. The two .mobileconfig files share one identifier, so installing one replaces the other.
Use one of these per machine. When a machine has more than one, Claude Code uses the highest-ranked one (the macOS profile or the Windows registry value over the file) and ignores the others.
Anthropic API:
json
{
"env": {
"ANTHROPIC_BASE_URL": "https://corveil.io"
},
"allowedProviders": [
"customEndpoint"
],
"wslInheritsWindowsSettings": true
}Amazon Bedrock:
json
{
"env": {
"CLAUDE_CODE_USE_BEDROCK": "1",
"ANTHROPIC_BEDROCK_BASE_URL": "https://corveil.io/v1/bedrock",
"AWS_REGION": "us-east-1",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "us.anthropic.claude-opus-5-5",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "us.anthropic.claude-sonnet-5-5",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "us.anthropic.claude-haiku-5-5"
},
"allowedProviders": [
"customEndpoint"
],
"wslInheritsWindowsSettings": true
}ANTHROPIC_BASE_URL(orANTHROPIC_BEDROCK_BASE_URLfor Bedrock) is your Corveil address. On a self-hosted instance the download has your own host in place ofcorveil.io.allowedProviders: ["customEndpoint"]makes Claude Code refuse every other way to reach Claude, such as a personal claude.ai login or AWS directly. It accepts the gateway only at the exact address the managedenvsets. SeeallowedProviders.wslInheritsWindowsSettingsmakes Claude Code inside WSL on a Windows machine follow the same policy. Without it, WSL reads only/etc/claude-code/managed-settings.jsoninside the distribution. Claude Code reads this key only from the Windows registry value orC:\Program Files\ClaudeCode\, so it has no effect on macOS or Linux.- Bedrock only:
AWS_REGIONand the three model pins above are the Bedrock guide's defaults. Your download fills in your own: your Bedrock credential's region, and for each tier the newest inference profile enabled in Catalog that the region can use. Where it can't, it keeps the default and shows a warning; enable the profile in Catalog and download again before you deploy. In the.regfile the settings are one JSON string: keep each"escaped as\"if you edit it.
Don't add forceLoginMethod, forceLoginOrgUUID or forceLoginGatewayUrl. With any value, they block every gateway credential at startup, and people see This machine's managed settings require a first-party login. If your managed settings set one today, for example to keep Claude logins to your Claude organization, remove it as part of this rollout. See Anthropic's gateway rollout guide.
Optional: fast mode (Anthropic API only). With only ANTHROPIC_AUTH_TOKEN as the credential, Claude Code doesn't run its fast mode check and treats fast mode as turned off by your organization. If your engineers use fast mode, add "CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK": "1" to env. If your network blocks api.anthropic.com, add "CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS": "1" as well. See fast mode behind gateways.
3. Test on one machine
- Install the file or profile on one machine, and add a key there as in step 4.
- Start
claude. If it refuses to start with an error about managed settings that couldn't be parsed, the file or registry value was damaged in transit or by an edit. Download it again. - Run
/statusand open the Status tab:Setting sourceslistsEnterprise managed settings, followed by(file),(plist)or(HKLM).- Anthropic API:
Anthropic base URLis your Corveil address, and anAuth tokenline namesANTHROPIC_AUTH_TOKEN. - Bedrock:
API providerisAmazon Bedrock, andBedrock base URLis your Corveil address followed by/v1/bedrock.
- Send a prompt that uses a tool, such as "list the files in this directory".
- In Corveil, open Monitoring → Logs. The turn is there under that person's key. Bedrock turns have provider
bedrock.
4. Give each person a key
Each person needs their own Corveil key in their own Claude Code settings, ~/.claude/settings.json (%USERPROFILE%\.claude\settings.json on Windows). Managed settings never carry a key.
- People create their own. Anyone whose role can create API keys opens People & Access → API Keys and creates one. Set an Expiration Date if you want keys to lapse.
- An admin issues them (in preview). Issuing keys is in preview: ask your Corveil contact to turn it on for your organization. Once it's on, choose API keys on the person's row in People & Access → Users, then Issue key. By default Corveil emails them a claim link. It works for 72 hours, and they see the key once when they open it while signed in. For keys IT holds, choose Show the key to me instead and hand the key over through your usual secrets process. The person can't change the limits, models or expiry you set on an issued key. Unclaimed links are listed under Governance → API keys → Waiting to be claimed.
- An admin creates one in their name. Without issuing, an admin can run
corveil control identity keys-create --user_id <their user ID> --team_id <team ID>and hand the key over through your usual secrets process.corveil control identity org-memberships-list <organization ID>lists each person's user ID.
Anthropic API:
json
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "sk-citadel-your-key-here"
}
}Amazon Bedrock:
json
{
"env": {
"AWS_BEARER_TOKEN_BEDROCK": "sk-citadel-your-key-here"
}
}ANTHROPIC_AUTH_TOKEN is sent as Authorization: Bearer and takes effect with no prompt. On Bedrock, leave CLAUDE_CODE_SKIP_BEDROCK_AUTH unset; see Which credential variable.
If someone signed in to Claude Code with a Claude account before, Claude Code warns at startup that two credentials are set. Running /logout once removes the saved login.
The VS Code extension checks for a credential before it starts, and it looks in its own claudeCode.environmentVariables setting, not in ~/.claude/settings.json. Anyone who uses the extension also adds the key there; see VS Code extension.
A key works until it expires or is revoked. Removing someone through directory sync revokes their keys. Suspending them in Okta doesn't; see Removing someone's access.
5. Deploy to the fleet
Push the file or profile with your device management tool. Claude Code reloads a managed settings file when it changes, and checks the macOS profile and the Windows registry value every 30 minutes.
Claude Desktop's Code tab
The Code tab in Claude Desktop doesn't use ANTHROPIC_BASE_URL or the key in ~/.claude/settings.json. It sends its requests, and signs in, through Claude Desktop's own gateway configuration. The Claude Desktop profile on the same Organization page already covers it. If people use both Claude Desktop and the claude command, deploy both profiles.
The Code tab does apply the rest of Claude Code's managed settings, allowedProviders included. On a machine that has both profiles, open a session in the Code tab during your one-machine test as well.
Limits
- Remote Control and voice dictation need a Claude account sign-in, so they don't work while Claude Code uses a Corveil key.
- Claude Code in Slack and on the web run in Anthropic's cloud, not on the managed machine, so they don't go through Corveil. If all usage must go through Corveil, don't turn them on for these people.
- Keys don't expire unless you set an expiry. Use directory sync, or disable the person's keys when someone leaves: on Governance → API keys (in preview, with issuing keys), which lists every key in the organization, or with
corveil control identity keys-update <key ID> --is_active false --yes.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
401 Unauthorized in Direct mode | The key isn't a valid Corveil virtual key | Check the value in ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN |
401 Unauthorized in Passthrough mode | The x-citadel-api-key header isn't a valid Corveil key, or the Anthropic credential is rejected | Check both |
| Claude Code asks you to log in | No credential reached Claude Code | Add the key to ~/.claude/settings.json as in step 4 |
This machine's managed settings require a first-party login | Managed settings set forceLoginMethod, forceLoginOrgUUID or forceLoginGatewayUrl | Remove them from managed settings |
| Claude Code refuses to start and names the managed settings | The managed file, profile or registry value doesn't parse | Download it again rather than editing it by hand |
| Claude Code refuses the API provider at startup | allowedProviders is in force and something set a different provider or address, such as CLAUDE_CODE_USE_BEDROCK on an Anthropic API machine | Remove the person's own provider or base URL settings, or deploy the profile for the mode they use |
/status has no Anthropic base URL line | The base URL didn't reach Claude Code | Check Setting sources for the managed settings, or set ANTHROPIC_BASE_URL |
| Startup warning about two credentials | A saved Claude login and a Corveil key are both set | Run /logout |
| Connection refused, or a long pause before an error | The base URL is wrong or unreachable | Check the address, then the network path to it |
| Custom headers not sent | ANTHROPIC_CUSTOM_HEADERS is malformed | Use header-name: value (colon, then a space) |