Skip to content

Claude Cowork ​

Use Claude Desktop (MDM) for a fleet. That guide locks Gateway mode, signs people in with interactive SSO, and runs managed-key. Anthropic is billed on the organization's API key stored as a Corveil provider credential. People do not paste a token.

This page is the manual, per-machine setup. It uses the older $schemaVersion: 2 JSON shape. On current Claude Desktop the Corveil key does not go in inference.customHeaders. That map is plain configuration, and a string value is dropped, so no custom headers are sent. Leave it unset. The helper prints the key inside its JSON headers.

Which credential ​

Managed-key is the fleet path on the MDM page. Passthrough on this page bills Anthropic on an API key you create in the Anthropic Console (sk-ant-api…). That key is the helper's token.

Claude Code, Claude Desktop, and claude.ai sign-in stay in those apps. The upstream credential here is an API key you provision. Anthropic bills that key. Spend limits count this traffic: an sk-ant-api… credential is per-token pass-through. Guardrails and request logs apply. Create the Corveil virtual key under People & Access → API Keys, or mint one with corveil login as described in the MDM guide.

Prerequisites ​

  • A running Corveil instance (see deployment options)
  • A Corveil virtual API key (sk-citadel-...) — create one under People & Access → API Keys
  • An Anthropic API key you create in the Anthropic Console (sk-ant-api…)

Mode ​

Passthrough mode with an Anthropic API key you provision. Cowork reads a versioned JSON inference config and sources that key from a helper script at request time.

For managed-key — budgets enforced, Anthropic billed on the organization's provider credential — use the MDM guide.

1. Configure the inference passthrough ​

Add the following to your Claude Cowork inference config. The credential.command is an absolute path to the helper script from the next step.

json
{
  "$schemaVersion": 2,
  "inference": {
    "provider": "gateway",
    "baseUrl": "https://corveil.io",
    "credential": {
      "kind": "helper-script",
      "command": "/Users/you/bin/anthropic-passthrough.sh"
    }
  },
  "chatSurface": {
    "enabled": true
  }
}

Field reference ​

  • $schemaVersion — config schema version; use 2.
  • inference.provider — must be gateway to route inference through Corveil.
  • inference.baseUrl — your Corveil host (https://corveil.io for the hosted gateway), with no /v1 suffix. Cowork calls GET /v1/models and POST /v1/messages on that origin.
  • inference.credential.kind — helper-script. Cowork runs the command and uses stdout as the credential. Do not also set interactive.
  • inference.credential.command — absolute path to the helper (below).
  • chatSurface.enabled — true turns on the Cowork chat surface. The flat profile key for the same switch is chatTabEnabled.

Leave inference.customHeaders out. The virtual key belongs in the helper's JSON headers, read from the secrets file below.

2. Install the credential helper ​

Save this as anthropic-passthrough.sh. It prints one JSON object. token is the Anthropic API key you provision (sk-ant-api…). headers carries the Corveil virtual key. Stdout must be that object and nothing else — do not print ANTHROPIC_CUSTOM_HEADERS or a bare token in front of it.

The script holds no secrets. It reads them at runtime from a 0600 file owned by the user. On a shared Mac, a world-readable script under /usr/local/bin would let any local user read the Anthropic API key.

sh
#!/bin/sh
# Mode 0700, owned by the user. Secrets stay in the 0600 file below.
set -eu
secrets="${HOME}/.config/corveil/anthropic-passthrough"
token=$(awk 'NR==1 { print; exit }' "$secrets")
key=$(awk 'NR==2 { print; exit }' "$secrets")
printf '{"token":"%s","headers":{"x-citadel-api-key":"%s"}}\n' "$token" "$key"

The secrets file is two lines: the Anthropic API key, then the Corveil virtual key. Both values are the real keys, ASCII only. A documentation ellipsis in either string (…, Unicode U+2026) makes the connection test fail before the request is sent. The same two values can live in the user keychain (macOS Keychain, Windows Credential Manager, or libsecret) when the helper reads that store instead of the file. The script does not mint a Corveil key.

bash
umask 077
mkdir -p "${HOME}/.config/corveil" "${HOME}/bin"
cat > "${HOME}/.config/corveil/anthropic-passthrough" <<'EOF'
sk-ant-api-your-key-here
sk-citadel-your-key-here
EOF
chmod 0600 "${HOME}/.config/corveil/anthropic-passthrough"
install -m 0700 anthropic-passthrough.sh "${HOME}/bin/anthropic-passthrough.sh"

Point credential.command at that absolute path (${HOME}/bin/anthropic-passthrough.sh). A relative path won't resolve when Cowork runs it. Cowork caches helper output (default one hour). Quit Cowork after you change the secrets file so it runs the helper again.

3. Confirm passthrough ​

  1. Sanity-check the helper by itself. Running it should print one JSON object. token is your Anthropic API key (sk-ant-api…). x-citadel-api-key is the virtual key:

    bash
    ./anthropic-passthrough.sh
  2. Launch Cowork and send a simple prompt.

  3. A successful passthrough returns a normal completion and the request shows up in Corveil. Confirm via the request log in the UI, or stream it:

    bash
    corveil logs-tail

If the prompt answers and the call appears in the Corveil logs, inference is round-tripping through the gateway.

Models Cowork will show ​

Cowork fills its picker from GET /v1/models on the gateway base URL. It keeps a row only when the model id contains claude, anthropic, sonnet, opus, haiku, fable, or mythos. Other catalog ids, including Kimi and Gemini, are ignored. A list that is entirely those ids shows up in the log as 0 usable models even though the HTTP call returned rows, and the connection test stays on an empty picker.

Enable at least one Claude model for the organization under AI Gateway → Providers → Catalog. The id Cowork displays is the id /v1/models returns. Enabling claude-opus-4-8 is enough for that model to appear; the non-Claude rows in the same response stay hidden. The virtual key in the helper has to belong to that organization.

Troubleshooting ​

  • 401 Passthrough mode requires an upstream Anthropic credential: x-citadel-api-key was sent without an sk-ant-api… token. The helper's token field must be an Anthropic API key you create in the Console.
  • 401 from Corveil about the virtual key: x-citadel-api-key is missing or invalid. Use a key from People & Access → API Keys, or one minted with corveil login.
  • Connection test: Cannot convert argument to a ByteString: a header value contains a non-ASCII character. The usual cause is a literal … left in sk-citadel-… or sk-ant-api-….
  • 0 usable models: /v1/models returned no Claude-family id. Enable one under AI Gateway → Providers → Catalog, then run the connection test again.
  • "permission denied" running the helper: confirm credential.command is the absolute path of a mode 0700 script you own, and that the secrets file is mode 0600.
  • Connection refused: ensure the Corveil instance is running and inference.baseUrl is reachable.