See everything you missed at TailscaleUp.Read the recap →

Set up an OpenAI-compatible provider

Last validated:

Configure an OpenAI-compatible provider in Aperture with the /v1/chat/completions API. Providers such as Groq, Together AI, Fireworks, Mistral, DeepSeek, and Perplexity expose OpenAI-compatible APIs. They are examples of this generic setup path, not individually verified integrations.

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

Tailscale does not test or guarantee compatibility with every OpenAI-compatible provider. Verify your provider's API requirements before configuring it. For servers such as llama.cpp, vLLM, or Ollama, refer to set up a self-hosted provider.

Prerequisites

Before you begin, you need:

  • An Aperture gateway accessible from your device. Refer to get started with Aperture if you have not set this up.
  • An API key from your provider's developer console or dashboard.
  • The provider's API base URL, including any required path prefix.

Configure the provider

Add your provider in your Aperture configuration:

{
  "providers": {
    "<provider-name>": {
      "baseurl": "https://api.example.com",
      "apikey": "<your-provider-key>",
      "models": ["<model-id-1>", "<model-id-2>"]
    }
  }
}

Replace the example values:

  • <provider-name>: A short identifier, such as groq or together.
  • <your-provider-key>: Your provider's API key.
  • baseurl: The provider URL prefix before the incoming /v1/... path.
  • models: The model IDs your provider supports. Find them in the provider's documentation or its /v1/models endpoint.

The default configuration uses openai_chat compatibility and bearer authorization. Change these settings if your provider requires a different API or authorization format.

If the provider's API base URL ends in /v1, remove only that suffix. Keep any earlier path segments. For example, use https://api.example.com/openai for an API base URL of https://api.example.com/openai/v1. Aperture appends the full incoming path, such as /v1/chat/completions, to baseurl. Keeping the final /v1 produces a doubled path. Refer to how Aperture builds upstream URLs for details.

Providers that also support the Responses API

If your provider supports the OpenAI Responses API (/v1/responses) in addition to chat completions, enable both compatibility flags explicitly:

{
  "providers": {
    "custom": {
      "baseurl": "https://api.example.com",
      "apikey": "<your-provider-key>",
      "models": ["model-name"],
      "compatibility": {
        "openai_chat": true,
        "openai_responses": true
      }
    }
  }
}

If you enable another flag and omit openai_chat, Aperture disables Chat Completions. Set "openai_chat": true to keep it enabled alongside Responses, or "openai_chat": false to disable it explicitly.

Non-standard authorization

Most OpenAI-compatible providers use bearer authorization, which is the default. If your provider requires a different authorization header, set the authorization field. Refer to the authorization types reference for the supported authorization types.

Cost estimation

Aperture infers the pricing source from the provider's baseurl host, then falls back to compatibility flags. With default Chat Completions compatibility, an unrecognized host uses openai pricing. Set cost_basis explicitly to use a different pricing source.

If your provider's model names are absent from that pricing source, use model_cost_map to map them to known models for cost estimation:

{
  "providers": {
    "<provider-name>": {
      "baseurl": "https://api.example.com",
      "apikey": "<your-provider-key>",
      "models": ["<model-id>"],
      "model_cost_map": [
        {"match": "<model-id>", "as": "<known-model-id>"}
      ]
    }
  }
}

Refer to the model cost map reference for the full syntax.

Verify the provider

The best way to verify a connection to a specific model is to send a test request through the Models tab of the Aperture dashboard.

  1. Open the Aperture dashboard and select the Models tab.
  2. Find the model you want to test in the list of configured models. If the model is not listed, check your provider configuration and ensure the model name is correct.
  3. Select the Play icon to the left of the model name to send a test request. If the request succeeds, the icon changes to a green check mark. If it fails, the icon changes to a red "X".

This sends a request from your web browser to the tailnet to verify that Aperture can successfully route requests to the model through the configured provider and that your user account has the necessary permissions to access the model.

Next steps