See everything you missed at TailscaleUp.Read the recap →

Set up the chat UI

Last validated:

Aperture Chat is available to authorized users at / and /chat by default.

To make chat usable, configure:

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

Without a models grant, the portal loads but the model picker is empty. You can also make matching non-admin users API-only by disabling portal access.

Prerequisites

Before you begin, make sure you have the following:

Step 1: Grant model access

Grant users access to at least one model whose provider supports a chat-compatible API.

Grants live under the tailscale.com/cap/aperture capability.

Open the Aperture admin dashboard and go to Administration > Grants.

Add a grant:

{
  "src": ["alice@example.com", "group:ai-users"],
  "app": {
    "tailscale.com/cap/aperture": [
      { "role": "user" },
      { "models": "anthropic/**" }
    ]
  }
}
  • models is the glob pattern for models the user can access. For the full syntax, refer to grant access to models.

To make matching non-admin users API-only, add enable_portal set to false to their grant. This disables the entire user portal, including chat. Admins always retain portal access. If any matching grant explicitly sets enable_portal to true, portal access remains enabled even when another matching grant sets it to false.

Group matching requires visible groups enabled for the Aperture gateway.

The grant examples on this page use Aperture configuration syntax, where the dst field is not required because the destination is the Aperture device itself. If you define grants in the tailnet policy file instead, you must include a dst key specifying the Aperture device (for example, "dst": ["tag:aperture"]). Omitting dst in a tailnet policy file grant causes the grant to silently have no effect. For a full comparison and conversion steps, refer to Aperture grants vs. tailnet policy file grants.

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 flagRoutes to
anthropic_messagesAnthropic Messages API
openai_chatOpenAI Chat Completions
openai_responsesOpenAI Responses API
gemini_generate_contentGemini
google_generate_contentGemini Enterprise Agent Platform (Gemini)

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-5-5", "claude-sonnet-5-5"],
      "compatibility": { "anthropic_messages": true }
    }
  }
}

Chat requests come from the Aperture gateway and have no client credential to forward. A provider in passthrough mode without a fallback apikey is passthrough-only. Its models do not appear in chat. Configure a fallback apikey to make them available.

For setup instructions, refer to Set up LLM providers. To compare APIs and requirements, refer to Supported providers and clients.

(Optional) Step 3: Curate the model picker

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 Administration > Chat > Models at /admin/settings/chat in the Aperture admin dashboard.

Verify access

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

  1. Have a granted user open / or /chat on the Aperture gateway. 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_portal to false. Refer to Troubleshooting Aperture for help diagnosing access issues.

Monitor chat usage

The Aperture admin dashboard includes an admin-only Chat Activity page at /admin/adoption/chat-activity.

Next steps