Best practicesClaude Desktop

Claude Desktop

Configure Claude Desktop Cowork on third-party inference so Cowork and Code sessions send model requests through Velrix. Use Gateway mode, bearer authentication, and an Anthropic-compatible base URL.

Use Claude Desktop's third-party inference Gateway mode.

Point Gateway Base URL at the Velrix Anthropic-compatible endpoint.

Add only exact model slugs that your Velrix workspace can route.

Before setup

Prerequisites

Prepare the desktop app, a scoped Velrix key, and the model slugs you want visible in Claude Desktop.

Claude Desktop

Use a recent build that exposes third-party inference.

Help -> Troubleshooting -> Enable Developer Mode

Velrix key

Use a dedicated key for Desktop Cowork and Code traffic.

vk_live_...

Base URL

Use the Anthropic-compatible endpoint, not the OpenAI-compatible endpoint.

https://api.velrix.ai

Gateway

Configure Gateway

Set up the local configuration from Claude Desktop while signed out, then apply it locally to test before any managed rollout.

Open the configuration UI

Stay signed out. Enable Developer Mode from Help - Troubleshooting, then open Developer - Configure third-party inference.

Choose Gateway

In the Connection section, choose Gateway, set the Velrix base URL, enter the API key, and choose Bearer as the auth scheme.

Inference provider

Claude Desktop third-party inference mode.

Gateway

Gateway Base URL

Anthropic Messages-compatible Velrix route.

https://api.velrix.ai

Gateway API Key

A scoped Velrix key.

vk_live_...

Gateway Auth Scheme

Send the key as Authorization: Bearer.

Bearer

Do not use the OpenAI-compatible URL here

Claude Desktop Gateway mode expects an Anthropic Messages-compatible endpoint. Use https://api.velrix.ai for Desktop and reserve /v1 OpenAI-compatible URLs for OpenAI SDK clients.

Models

Model list

Add exact model IDs that your Velrix workspace supports. Start with automatic routing when your policy allows it, then pin models for predictable review or coding workflows.

Model slugs


claude-sonnet-4.6
claude-opus-4.7

Use exact slugs

Copy model IDs from the Velrix catalog. Misspelled IDs can make Desktop fail at session start or return model-not-found errors.

Enable 1M context deliberately

Turn on long-context options only for models and provider routes that explicitly support that context length.

Administration

Managed rollout

For teams, test locally first, then export the validated configuration through the Claude Desktop UI for your MDM or policy tooling.

Managed keys

inferenceProvider = "gateway"
inferenceGatewayBaseUrl = "https://api.velrix.ai"
inferenceGatewayApiKey = "sk-vx-..."
inferenceGatewayAuthScheme = "bearer"
inferenceModels = "[\"claude-sonnet-4.6\"]"

Prefer the UI for authoring

Claude's configuration window validates provider fields and can export macOS or Windows managed configuration artifacts. Use hand authored keys only when you need to audit or integrate with existing policy generation.

Research

References

These external references informed the Claude Desktop setup flow and Gateway fields shown above.

ZenMux Claude Desktop integration guide

Reference flow for enabling Developer Mode, opening third-party inference settings, configuring Gateway mode, and testing model slugs.

Claude Cowork on third-party installation

Official Anthropic setup flow for evaluating locally, exporting MDM profiles, and verifying deployments.

Claude Cowork on third-party configuration reference

Official key reference for inferenceProvider, inferenceGatewayBaseUrl, inferenceGatewayApiKey, auth scheme, model list, and security controls.

Operations

Verify traffic

Apply locally, let Claude Desktop restart, then send a simple prompt and confirm the request landed on the expected Velrix key and route.

View request logs Review API keys