# Set up an OpenAI-compatible provider

Last validated Aug 21, 2026

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.

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

> **Note:**
>
> 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][docs-use-self-hosted].

## Prerequisites

Before you begin, you need:

* An Aperture gateway accessible from your device. Refer to [get started with Aperture][docs-aperture-get-started] 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][docs-aperture-configuration]:

```json
{
  "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.

> **Warning:**
>
> 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][docs-aperture-url-construction] 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:

```json
{
  "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][docs-provider-compatibility] 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][docs-provider-compatibility-cost-basis], 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:

```json
{
  "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][docs-provider-compatibility-model-cost-map] reference for the full syntax.

## Verify the provider

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

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

[docs-aperture-configuration]: /docs/aperture/configuration

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

[docs-aperture-url-construction]: /docs/aperture/configuration#how-aperture-builds-upstream-urls

[docs-provider-compatibility]: /docs/aperture/provider-compatibility

[docs-provider-compatibility-cost-basis]: /docs/aperture/provider-compatibility#cost-basis

[docs-provider-compatibility-model-cost-map]: /docs/aperture/provider-compatibility#model-cost-map

[docs-use-self-hosted]: /docs/aperture/how-to/use-self-hosted