Skip to content

Claude Desktop

Point managed Claude Desktop on 3P at CloudService using its supported Gateway configuration.

This guide is for Claude Desktop on third-party (3P), Anthropic's managed deployment mode. It does not replace the provider for a normal consumer Claude.ai account or its hosted chats. Choose the tab that matches the type of CloudService key you created; the correct base URL is different for API-credit and Claude-token keys.

Requirements

Use a Claude Desktop version that includes third-party inference and a deployment where you are allowed to apply a local 3P configuration or distribute managed settings. The gateway supports streaming and tool use on POST /v1/messages, local input estimates on POST /v1/messages/count_tokens, and authenticated model discovery on GET /v1/models.

Choose your key type

Configure the route that matches your key

Select one setup. These are different gateway origins, so the key type and base URL must stay together.

For an API-credit CloudService key

API Credit setup

Use this route when the key is funded with API credits. Claude Desktop sends Anthropic Messages requests through the standard CloudService gateway.

1. Open Claude Desktop's 3P configuration

  1. In Claude Desktop, open Help → Troubleshooting → Enable Developer Mode, then choose Developer → Configure third-party inference.
  2. For one Windows or macOS machine, enter the settings below and choose Apply locally.
  3. For managed devices, use Export from that screen. Deploy the exported .reg on Windows, .mobileconfig on macOS, or bootstrap JSON with your device-management tool. Do not hand-edit Claude Desktop's internal files.

This guide applies only to Claude Desktop's managed third-party inference (3P) mode. It does not configure normal consumer Claude.ai chats, and Claude Desktop does not read Claude Code's settings or environment variables.

2. Enter these connection settings

  • Inference provider: Gateway
  • Gateway base URL: https://api.yourdomain.example
  • Credential kind: Static API key
  • Gateway API key: YOUR_CLOUDSERVICE_API_KEY — use the API-credit key created for this user or device.
  • Gateway auth scheme: Bearer

Key compatibility: The API-credit key must include Claude provider access. A key restricted to OpenAI cannot populate Claude models in Desktop.

Use the origin exactly as shown. Do not append /v1; Claude Desktop adds the Anthropic API path itself. For this selection, requests resolve to https://api.yourdomain.example/v1/messages.

3. Keep model discovery enabled

Leave discovery on so Claude Desktop authenticates to https://api.yourdomain.example/v1/models with the same Bearer key and populates its model picker. The current Claude IDs are:

  • claude-haiku-4-5-20251001
  • claude-opus-4-6
  • claude-opus-4-7
  • claude-opus-4-8
  • claude-opus-5
  • claude-sonnet-5
  • fable-5

If your organization requires a fixed model list, export the settings from Claude Desktop after discovery succeeds; use the export's encoding for managed policy values.

4. Review the managed configuration values

The configuration screen validates and exports these logical values. The API key remains a static Bearer credential; do not replace it with a browser login token.

credit-mode-gateway.json
{
  "inferenceProvider": "gateway",
  "inferenceGatewayBaseUrl": "https://api.yourdomain.example",
  "inferenceGatewayApiKey": "YOUR_CLOUDSERVICE_API_KEY",
  "inferenceCredentialKind": "static",
  "inferenceGatewayAuthScheme": "bearer"
}

5. Verify with one small request

Before opening a Desktop chat, use this one-token probe. It verifies the selected gateway route and key without sending a long prompt.

credit-mode-check.sh
export CLOUDSERVICE_API_KEY="YOUR_CLOUDSERVICE_API_KEY"

curl -sS https://api.yourdomain.example/v1/messages \
  -H "Authorization: Bearer $CLOUDSERVICE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001","max_tokens":1,"messages":[{"role":"user","content":"K"}]}'

On Windows PowerShell, use this equivalent command:

credit-mode-check.ps1
$env:CLOUDSERVICE_API_KEY = "YOUR_CLOUDSERVICE_API_KEY"
$body = @{ model = "claude-haiku-4-5-20251001"; max_tokens = 1; messages = @(@{ role = "user"; content = "K" }) } | ConvertTo-Json -Depth 5 -Compress

curl.exe -sS "https://api.yourdomain.example/v1/messages" `
  -H "Authorization: Bearer $env:CLOUDSERVICE_API_KEY" `
  -H "anthropic-version: 2023-06-01" `
  -H "content-type: application/json" `
  -d $body

Then fully quit and reopen Claude Desktop. Confirm it starts in 3P mode, the model picker includes the discovered CloudService Claude models, and a short test message succeeds.

Troubleshooting this mode

  • 401 or invalid credential: confirm the key is active, paste it without spaces or quotes, and use API Credit with https://api.yourdomain.example. Do not post the key in screenshots or support messages.
  • 404 or rejected gateway URL: remove /v1 from the base URL field. The field takes the origin, not the Messages endpoint.
  • No models in the picker: fully quit and reopen Desktop, verify that https://api.yourdomain.example/v1/models is reachable with the same key, and check whether an MDM policy is overriding local settings.
  • Local settings do not stick: use the app's Export action and have your Windows or macOS management policy install the generated artifact.
  • Allowance unavailable: If the API-credit balance is depleted, add API credits or use a different active API-credit key. A Claude-token key cannot be used on this route.

Enable safe GitHub skill tools

Third-party inference configures the model connection, but it does not automatically grant the desktop app network or filesystem tools. Install CloudService's bounded GitHub MCP after the gateway is working:

bash
npm install -g cloudservice@latest
cloudservice claude-tools

Restart Claude Desktop, then use Cowork or Code. The normal Chat tab does not expose local tools. Claude will receive github_fetch, github_tree, and github_install_skill.

The MCP accepts only public GitHub HTTPS hosts, limits response and archive sizes, rejects unsafe paths and symlinks, refuses to overwrite existing skills, and writes only below ~/Claude/skills. It does not grant a general shell, arbitrary URL access, or unrestricted filesystem access.

Review the repository before installing. A SKILL.md is instruction content that Claude may follow; the bridge does not execute repository code, but trusted source is still required.

You can request, for example: Install the template skill from anthropics/skills on GitHub. Claude must ask for confirmation before the write-capable install tool runs.

Keep the key private

The desktop configuration contains a long-lived credential. Do not share the exported profile publicly or check it into source control. Use a separate per-user or per-device CloudService key where possible so it can be revoked independently.

See Claude Desktop's official LLM gateway guide and in-app configuration guide for deployment details.