# Use Claude Desktop with Aperture

Last validated Jul 20, 2026

\[Missing snippet: aperture\_release\_note.mdx]

Configure the [Claude Desktop][xt-claude-desktop] app to send model requests through [Aperture by Tailscale][kb-aperture] 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.

> **Note:**
>
> The [Aperture CLI][kb-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][ar-use-amazon-bedrock-models] instead, configure the gateway manually with the steps in this guide.

> **Note:**
>
> 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][ar-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][kb-get-started] if you have not set this up.
* The Aperture host URL accessible from your device over `https://`.
* The [Claude Desktop][xt-claude-desktop] app installed on macOS.

> **Warning:**
>
> 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][kb-aperture-cli] applies the correct URL format automatically.

\[Missing snippet: aperture\_any\_provider.mdx]

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:

   | Field        | Value               |
   | ------------ | ------------------- |
   | Model ID     | `claude-sonnet-4-6` |
   | Display name | Claude Sonnet 4.6   |
   | Tier alias   | `sonnet`            |

8. Select **Save Changes**, then **Apply Changes**.

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

> **Note:**
>
> 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][kb-use-amazon-bedrock] 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:

| Field        | Value                            |
| ------------ | -------------------------------- |
| Model ID     | `us.anthropic.claude-sonnet-4-6` |
| Display name | Claude Sonnet 4.6 (Bedrock)      |
| Tier alias   | `sonnet`                         |

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][kb-use-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][kb-aperture-troubleshooting].

## 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:

   | Format                       | File            | Use with                                      |
   | ---------------------------- | --------------- | --------------------------------------------- |
   | macOS configuration profile  | `.mobileconfig` | Jamf, Kandji, Intune, and other MDM platforms |
   | Windows registry file        | `.reg`          | Windows deployment tooling                    |
   | Group Policy template (ADMX) | `.zip`          | Intune 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.

> **Note:**
>
> 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.

\[Missing snippet: aperture\_connect\_next\_steps.mdx]

[ar-deploy-across-a-fleet-with-mdm]: #deploy-across-a-fleet-with-mdm

[ar-use-amazon-bedrock-models]: #use-amazon-bedrock-models

[kb-aperture-cli]: /docs/aperture/cli

[kb-aperture-troubleshooting]: /docs/aperture/troubleshooting

[kb-aperture]: /docs/aperture

[kb-get-started]: /docs/aperture/get-started

[kb-use-amazon-bedrock]: /docs/aperture/how-to/use-amazon-bedrock

[xt-claude-desktop]: https://claude.ai/download