Last chance to meet us at TailscaleUp!Grab your ticket ->

Set up an OpenAI-compatible provider

Last validated:

Configure any provider that exposes an OpenAI-compatible API as a provider in Aperture. Aperture works with any service that serves the /v1/chat/completions endpoint, not only the providers with dedicated topics. Providers such as Groq, Together AI, Fireworks, Mistral, DeepSeek, and Perplexity all expose OpenAI-compatible APIs and work with the default openai_chat compatibility flag and bearer authorization.

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.

Tailscale does not test or guarantee compatibility with every OpenAI-compatible provider. Verify that your provider serves the /v1/chat/completions endpoint before configuring it. For self-hosted LLM 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. This is the root URL without a /v1 path segment.

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 <provider-name> with a short identifier for the provider (for example, groq or together). Replace <your-provider-key> with the API key from your provider. Set baseurl to your provider's API root, and list the model IDs your provider supports in models. To find model IDs, check your provider's documentation or query their /v1/models endpoint.

OpenAI-compatible providers use the openai_chat compatibility flag and bearer authorization by default, so no additional flags are needed.

Do not include /v1 in the provider's baseurl. Aperture appends the full incoming request path to baseurl, so including /v1 produces a doubled path such as /v1/v1/chat/completions. 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
      }
    }
  }
}

When you include a compatibility block, set openai_chat explicitly. Including a compatibility block without naming openai_chat clears the default, which disables the /v1/chat/completions endpoint for that provider.

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 provider compatibility reference for the supported authorization types.

Cost estimation

Aperture auto-infers pricing from the provider's baseurl host and compatibility flags. For providers not in the recognized host list, Aperture cannot infer a pricing source. Requests still route correctly, but cost estimates, quota deductions, and dashboard pricing are unavailable for that provider.

To enable cost estimation for an unlisted provider, use model_cost_map to map your provider's model names to known models:

{
  "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