See everything you missed at TailscaleUp.Read the recap →

Use OpenAI-compatible tools with Aperture

Last validated:

Configure OpenAI-compatible LLM clients to send requests through Aperture by Tailscale. This guide describes the generic setup for clients with a configurable API base URL and an OpenAI-compatible API back end. Roo Code, Cline, and custom applications are examples of this path, not individually verified integrations.

For client-specific instructions, refer to the guides for Claude Code, Codex, and OpenCode.

Gemini CLI uses native Google Gemini APIs, not the OpenAI-compatible setup in this guide. Follow the Gemini CLI setup for its Google back ends and gateway URL requirements.

Prerequisites

Before you begin, you need:

  • An Aperture gateway with a provider that supports your client's API format and model. OpenAI Chat Completions and Responses are separate formats. Refer to get started with Aperture for setup instructions.
  • Permission to use the model.
  • The Aperture host URL accessible from your device. Use http://, not https://.

To avoid unexpected TLS issues, use http:// for the Aperture URL when configuring LLM clients. All connections remain encrypted using WireGuard, even when HTTPS is not used.

Your client and selected provider must support the same API format. Refer to Supported providers and clients for available setup options and requirements.

Configure the client

In your LLM client's settings, set the API base URL to your Aperture gateway and configure credentials for the provider's authentication mode:

  • API Base URL: http://<aperture-hostname>/v1
  • API Key: For a shared-key provider, leave empty or use a placeholder. In passthrough mode, supply provider credentials or leave empty to use a configured fallback key. Refer to passthrough setup for the required credentials.

The exact setting names vary by client. Look for fields labeled "API Base URL," "Base URL," "API Endpoint," or similar.

Custom applications

You can use any HTTP client that sends a supported provider API format. This Chat Completions example uses a shared-key provider. For a passthrough provider without a fallback key, add the authentication header required by its passthrough setup.

curl -s http://<aperture-hostname>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Aperture routes the request using the model name, API format, provider configuration, and user permissions.

Verify the connection

  1. Send a test request using your configured tool.
  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 guide.

Next steps