# Set up the chat UI

Last validated Jun 27, 2026

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

The chat UI is a conversational interface, served at `/chat/`, that lets your users talk to LLMs directly through Aperture without configuring a separate client. This guide covers how to enable the chat UI for your users and curate the models available to them.

The chat UI is available to your users by default. To make it usable, you configure:

* **Models**: Give users a `models` grant for at least one model whose provider declares a chat-compatible API.
* **Curation** (optional): Narrow and label the models that appear in the chat model picker.

Without a `models` grant, the interface loads but gives users nothing to talk to, so a `models` grant is always required. You can also turn the chat UI off for specific users.

## Prerequisites

Before you begin, ensure you have the following:

* An [Aperture instance][kb-get-started] with at least one configured provider.
* [Admin access][kb-set-up-admin-access] to the Aperture dashboard.
* Users who can already [reach the Aperture device][kb-grant-model-access] over your tailnet.

## Step 1: Grant model access

The chat UI is available by default to any user who can reach the Aperture device. To give them something to talk to, grant access to at least one model whose provider declares a chat-compatible API. Without a `models` grant, the model picker is empty.

Grants live under the `tailscale.com/cap/aperture` capability. Open the **Settings** page of the Aperture dashboard and add a grant:

```json
{
  "src": ["alice@example.com", "group:ai-users"],
  "app": {
    "tailscale.com/cap/aperture": [
      { "role": "user" },
      { "models": "anthropic/**" }
    ]
  }
}
```

* `models` is the glob of models the user can reach. Without it, the model picker is empty. For the full pattern syntax, refer to [grant access to models][kb-grant-model-access].

To turn the chat UI off for specific users, add `enable_chat_ui` set to `false` to their grant. The chat UI stays available to everyone else.

Group matching requires [visible groups][kb-visible-groups] enabled for the Aperture device.

\[Missing snippet: aperture\_grant\_dst\_note.mdx]

## Step 2: Configure a chat-compatible provider

A model appears in the chat UI only if its provider declares a chat API in its `compatibility` block. Configure at least one provider with one of the following flags:

| Compatibility flag        | Routes to               |
| :------------------------ | :---------------------- |
| `anthropic_messages`      | Anthropic Messages API  |
| `openai_chat`             | OpenAI Chat Completions |
| `openai_responses`        | OpenAI Responses API    |
| `gemini_generate_content` | Gemini                  |
| `google_generate_content` | Vertex AI (Gemini)      |

The following example configures an Anthropic provider for the chat UI:

```json
{
  "providers": {
    "anthropic": {
      "name": "Anthropic",
      "baseurl": "https://api.anthropic.com",
      "apikey": "<your-anthropic-key>",
      "authorization": "x-api-key",
      "models": ["claude-opus-4-8", "claude-sonnet-4-6"],
      "compatibility": { "anthropic_messages": true }
    }
  }
}
```

The provider must have a credential the chat UI can use. Chat requests originate on the Aperture device and carry no client credential, so a provider configured in [passthrough mode][kb-use-passthrough-mode] with no fallback `apikey` (a passthrough-only provider) does not show its models in the chat UI. To use such a provider in the chat UI, configure a fallback `apikey`.

For provider-specific setup, refer to the [set up providers][kb-set-up-providers] guides. For the full list of providers and API formats, refer to the [provider compatibility reference][kb-provider-compatibility].

## Step 3: Curate the model picker (optional)

By default, every chat-compatible model a user is granted appears in the model picker. To narrow the list or relabel models, set the top-level `chat_models` list in your Aperture configuration. When `chat_models` is non-empty, only models matching one of its entries appear in the picker.

```json
{
  "chat_models": [
    { "model": "anthropic/**", "display_name": "Claude", "priority": 100 },
    { "model": "openai/**", "title_gen": true },
    { "model": "*/internal-*", "hidden": true }
  ]
}
```

Each entry takes a `model` glob in `provider/model` format and these optional fields:

* `display_name`: Label shown in the model picker instead of the model ID.
* `priority`: Sort order in the picker. Higher values appear first.
* `title_gen`: Use this model to generate conversation titles.
* `summarize`: Use this model to summarize chain-of-thought segments.
* `hidden`: Exclude matching models from the picker while keeping them eligible for `title_gen` and `summarize`. Use this to reserve a model for background tasks without offering it for responses.

`chat_models` is a curation list only. It does not grant access: a model appears in the picker only if the user's `models` grant covers it. You can also edit this list from the **Chat** admin page in the Aperture dashboard.

## Verify access

After you configure access, providers, and curation, verify that the chat UI works:

1. Have a granted user open `/chat/` on the Aperture device. The model picker should list the curated models.
2. Send a test message and confirm a response.

If a user reaches the chat UI but the model picker is empty, check that their `models` grant covers a model whose provider declares a chat `compatibility` flag. If a user cannot open the chat UI at all, confirm their grant does not set `enable_chat_ui` to `false`. Refer to [Troubleshooting Aperture][kb-troubleshooting] for help diagnosing access issues.

## Monitor chat usage

The Aperture dashboard includes admin-only views for chat:

* **Chat activity** (`/adoption/chat-activity`): Adoption metrics for the chat UI.

## Next steps

* [Grant access to models][kb-grant-model-access] to refine which models each user or group can reach.
* [Set per-user spending limits][kb-set-per-user-spending-limits] to manage costs.
* Refer to the [Aperture dashboard reference][kb-web-dashboard] for details on each admin-accessible page.

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

[kb-grant-model-access]: /docs/aperture/how-to/grant-model-access

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

[kb-set-per-user-spending-limits]: /docs/aperture/how-to/set-per-user-spending-limits

[kb-set-up-admin-access]: /docs/aperture/how-to/set-up-admin-access

[kb-set-up-providers]: /docs/aperture/set-up-providers

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

[kb-use-passthrough-mode]: /docs/aperture/how-to/use-passthrough-mode

[kb-visible-groups]: /docs/aperture/visible-groups

[kb-web-dashboard]: /docs/aperture/reference/dashboard