Claude Desktop

Claude Desktop is Anthropic’s desktop application. It is not a coding agent in the Claude Code sense, but it is the client most of your organisation actually opens every morning, and it ships with a feature built for exactly this: a third-party inference gateway, where you point the app at an Anthropic-compatible endpoint of your choosing instead of Anthropic’s own. That endpoint is the firewall.

Why put Claude Desktop behind the firewall

• Your provider key never sits in the app’s config. Claude Desktop carries your Vulnetix API key. Your Anthropic key stays in the KMS-encrypted BYOK vault and is decrypted just-in-time by the gateway, on the server side of the request.
• Every prompt the client sends is screened by your guardrails — including the contents of files people attach or paste, and, where the app is driving tools, the output those tools feed back into the conversation as tool results.
• Provider and model policy is enforced centrally. The model picker cannot reach a model your organisation has not approved: the decision is made at the gateway, on every request, not in a local setting a user can edit.

Quick start

vulnetix ai-firewall key set anthropic --from-env ANTHROPIC_KEY

How it works

Claude Desktop sends POST /v1/messages to https://guardrails.vulnetix.com/anthropic/{orgUuid} — the gateway’s messages surface, the same one Claude Code uses. The gateway authenticates your Vulnetix API key to your organisation, applies provider and model policy, runs your guardrails over every text segment in the request, decrypts your Anthropic key from the vault, and forwards the call. Prompts and completions are never logged.

No local proxy is required. This is a first-class feature of the application; you are using it as designed, with your own endpoint.

Verify

The check is in the app itself. After the restart, the start screen offers Continue with Gateway — if it does not, the setting did not take, and you should re-open Developer → Configure Third-Party Inference… and confirm it was applied locally.

Once you are in, open the model picker. The models listed are the ones the gateway returned, so a picker that shows your organisation’s approved models — and not Anthropic’s full catalogue — is positive confirmation that you are talking to the firewall.

From a terminal on the same machine:

vulnetix ai-firewall status

Claude Desktop appears as manual, which means “the CLI does not manage this client” — not “this client is wired”. The CLI cannot read the app’s internal settings, so it cannot confirm the base URL for you. Trust the start screen instead.

Limitations

• The setting is per-machine and per-user, and nothing enforces it. A user who turns developer mode back off, or signs in with an Anthropic account instead of choosing Continue with Gateway, is talking to Anthropic directly again. There is no configuration file you can ship to a fleet to prevent that.
• vulnetix ai-firewall status cannot verify Claude Desktop. Because the CLI does not manage it, Claude Desktop can never raise a bypasses_firewall warning. Absence of a warning is not evidence that this client is firewalled.
• The arguments the model generates for a tool call are not scanned. Prompt content and tool results are.

If your control narrative depends on Claude Desktop being firewalled, that claim rests on user behaviour, not on a technical control. Treat it accordingly.

Common errors

401 — invalid Vulnetix API key

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "invalid Vulnetix API key"
  }
}

Almost always the two-keys confusion: the API key field is holding an Anthropic key (sk-ant-…) instead of your Vulnetix API key. The gateway authenticates you with the Vulnetix key; it supplies the Anthropic key itself, from the vault. Your provider key belongs in the vault, never in the app.

Fix:

1. Store your Anthropic key: vulnetix ai-firewall key set anthropic --from-env ANTHROPIC_KEY.
2. In Configure Third-Party Inference…, replace the API key with your Vulnetix API key.
3. Confirm the auth scheme is bearer.
4. Apply, fully quit, and reopen.

403 — provider_key_missing

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "code": "provider_key_missing",
    "message": "no Anthropic API key configured for your organisation: add one with 'vulnetix ai-firewall key set anthropic' or at https://www.vulnetix.com/vdb-ai-firewall#byok"
  }
}

You are authenticated, but your organisation has no Anthropic key in the vault, so the gateway has nothing to forward the request with. This typically shows up as an empty model picker, because the model list call fails for the same reason.

Fix:

1. export ANTHROPIC_KEY=sk-ant-...
2. vulnetix ai-firewall key set anthropic --from-env ANTHROPIC_KEY
3. vulnetix ai-firewall status — the anthropic row should now show a stored key.
4. Restart Claude Desktop so it re-fetches the model list.

403 — model_not_allowed

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "code": "model_not_allowed",
    "message": "model claude-opus-4-1 is not in the organisation allowlist"
  }
}

Your organisation runs an allowlist for this provider and the selected model is not on it. (A model that is explicitly denied returns model_denied instead.) You can still hit this even though the picker is populated from the gateway, if the app is holding a model it selected before the policy changed.

Fix:

1. Reopen the model picker and choose a model the gateway currently offers.
2. Run vulnetix ai-firewall get to see the policy, or ask your administrator.
3. If the model should be allowed, an administrator adds it to the policy — then restart the app to refresh the list.

404 — unsupported_api

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "code": "unsupported_api",
    "message": "provider openai does not support the Anthropic Messages API (POST /v1/messages). Use POST /v1/chat/completions for openai, or point your Anthropic client at a provider that serves the Messages API: https://guardrails.vulnetix.com/anthropic/{orgUuid} (note: no /v1 suffix — the Anthropic SDK appends it)"
  }
}

Your base URL is wrong in one of two ways: the provider slug is not anthropic, or you appended /v1 and the client appended a second one on top.

Fix:

1. Open Developer → Configure Third-Party Inference….
2. Set the base URL to exactly https://guardrails.vulnetix.com/anthropic/{orgUuid} — the slug anthropic, and no trailing /v1.
3. Apply, fully quit, and reopen.