Set up the chat UI

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 with at least one configured provider.
• Admin access to the Aperture dashboard.
• Users who can already reach the Aperture device 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:

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

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 enabled for the Aperture device.

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:

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

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

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

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.

{
  "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 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 to refine which models each user or group can reach.
• Set per-user spending limits to manage costs.
• Refer to the Aperture dashboard reference for details on each admin-accessible page.