Join us in San Francisco for TailscaleUp!Grab your ticket ->

Use Claude Desktop with Aperture

Last validated:
Aperture by Tailscale is currently in beta.

Configure the Claude Desktop app to send model requests through Aperture by Tailscale so your organization gets centralized API key management, usage tracking, and session logging.

Claude Desktop routes inference to any gateway that implements the Anthropic Messages API. Aperture serves this API, so you point Claude Desktop's gateway connection at your Aperture host.

The Aperture CLI can set up this connection for you automatically. It writes the gateway configuration and normalizes the host URL, so you can skip the manual steps below. The CLI lists Claude Desktop as Claude Cowork and configures the Anthropic backend. To use Amazon Bedrock models instead, configure the gateway manually with the steps in this guide.

The manual configuration steps in this guide use the macOS Claude Desktop app and its menu paths. To deploy to Windows devices, refer to Deploy across a fleet with MDM.

Prerequisites

Before you begin, you need:

  • An Aperture instance with at least one configured AI provider (such as Anthropic), accessible from your device. Refer to get started with Aperture if you have not set this up.
  • The Aperture host URL accessible from your device over https://.
  • The Claude Desktop app installed on macOS.

Claude Desktop requires an https:// gateway URL and rejects http://, unlike most Aperture LLM clients. Point it at your Aperture host's HTTPS URL; Tailscale provisions a TLS certificate for tailnet hostnames, and traffic stays encrypted over WireGuard. The Aperture CLI applies the correct URL format automatically.

Aperture routes requests based on the model name, not the LLM client. Any LLM client configured to use Aperture can access any provider your admin has set up. Refer to the provider compatibility reference for the full list of supported providers and API formats.

Claude Desktop's gateway connection is a per-user setting. Each person who uses Aperture configures it on their own device, or an admin deploys it across a fleet with MDM.

Enable Developer Mode

The gateway connection lives behind Developer Mode:

  1. In the menu bar, select Help > Troubleshooting > Enable Developer Mode.
  2. Claude Desktop might restart. When Developer Mode is active, Developer appears in the menu bar.

Configure the gateway connection

Open the third-party inference configuration and point it at your Aperture host:

  1. Select Developer > Configure Third-Party Inference.

  2. Set the connection type to Gateway.

  3. Set Credential kind to Static API key.

  4. Set Gateway base URL to your Aperture URL:

    https://<aperture-hostname>

  5. Set Gateway API key to any non-empty placeholder, such as aperture. The field cannot be empty, but Aperture requires no API key and ignores the value. Aperture authenticates requests by tailnet identity and injects provider credentials automatically.

  6. Leave the Custom inference headers section empty. Aperture does not require an authorization header.

  7. In the Models section, add at least one model your admin has configured in Aperture. Aperture does not expose a discoverable model list, so enter models manually rather than relying on model discovery. For example:

    FieldValue
    Model IDclaude-sonnet-4-6
    Display nameClaude Sonnet 4.6
    Tier aliassonnet

  8. Select Save Changes, then Apply Changes.

  9. Fully quit and reopen Claude Desktop to load the new configuration.

Aperture routes to the native Anthropic Messages API (/v1/messages). Keep the connection type set to Gateway, not an OpenAI-compatible option.

Use Amazon Bedrock models

If your Aperture instance has an Amazon Bedrock provider configured, Claude Desktop can use Bedrock-hosted Claude models through the same gateway connection. Aperture hides the provider from Claude Desktop, so the only change is the model IDs you enter in the Models section.

In the Models section of the gateway configuration, add the Bedrock model IDs your admin has configured in Aperture. These use Bedrock's naming convention, including the region prefix and version suffix, and must match the model names in your Aperture configuration exactly. For example:

FieldValue
Model IDus.anthropic.claude-sonnet-4-6
Display nameClaude Sonnet 4.6 (Bedrock)
Tier aliassonnet

Aperture routes these requests to Bedrock and injects the AWS credentials, so Claude Desktop needs no AWS configuration of its own. To set up the provider, refer to Set up Amazon Bedrock.

Verify the connection

To verify that Claude Desktop routes requests through Aperture:

  1. Start a conversation in Claude Desktop and send a test message.
  2. Open the Aperture dashboard at http://<aperture-hostname>/ui/ and confirm the request appears on the Logs page (admin only).

If the request does not appear, refer to the Aperture troubleshooting topic.

Deploy across a fleet with MDM

Because the gateway connection is a per-user setting, an admin can push it to every managed device instead of having each person configure it by hand. Claude Desktop's Export feature turns a working configuration into a deployment file for your device management platform.

To generate and deploy the configuration:

  1. Configure the gateway connection on one device using the steps above, and confirm it works.

  2. In the Configure Third-Party Inference window, open the Export dropdown at the top.

  3. Choose the format that matches your management platform:

    FormatFileUse with
    macOS configuration profile.mobileconfigJamf, Kandji, Intune, and other MDM platforms
    Windows registry file.regWindows deployment tooling
    Group Policy template (ADMX).zipIntune or Group Policy managed consoles

  4. Deploy the exported file with your management platform. For example, on macOS, push the .mobileconfig profile through your MDM to set managed preferences under the com.anthropic.claudefordesktop domain, which locks the gateway connection for every managed device.

The export writes the placeholder API key into the file in plain text. Because Aperture requires no API key, this value is not a secret and the exported file contains no real credentials.

Next steps