{"slug":"aperture-by-tailscale-configuration","title":"Aperture by Tailscale configuration","tags":["tailscale"],"agent_summary":"Last validated: Apr 9, 2026","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Aperture by Tailscale configuration\r\n\r\nLast validated: Apr 9, 2026\r\n\r\nAperture by Tailscaleis currently [in alpha](https://tailscale.com/docs/reference/tailscale-release-stages#alpha).\r\n\r\nDuring the alpha testing period, Aperture by Tailscale is available at no additional cost across [all Tailscale plans](https://tailscale.com/pricing). Request access at [`aperture.tailscale.com`](https://aperture.tailscale.com/). Aperture by Tailscale comes with six free users. Contact Tailscale for pricing if you need more than six users.\r\n\r\n[Aperture by Tailscale](https://tailscale.com/docs/aperture) uses a JSON configuration to specify LLM providers, access control policies, and optional integrations. The Aperture configuration controls which models are available, how requests authenticate with upstream providers, and who can access what. Admins can edit the configuration from the **Settings** page of the [Aperture dashboard](https://tailscale.com/docs/aperture/reference/dashboard) using the **Visual editor** (default) or the **JSON editor**.\r\n\r\nThis page is part of the [Aperture reference](https://tailscale.com/docs/aperture/reference) documentation.\r\n\r\n## [Minimal configuration](https://tailscale.com/docs/aperture/configuration\\#minimal-configuration)\r\n\r\nA minimal configuration requires at least one provider with a base URL and at least one model. The following example shows a minimal configuration:\r\n\r\n```json\r\n{\r\n \"providers\": {\r\n \"anthropic\": {\r\n \"baseurl\": \"https://api.anthropic.com\",\r\n \"apikey\": \"YOUR_ANTHROPIC_API_KEY\",\r\n \"models\": [\\\r\n \"claude-sonnet-4-5\",\\\r\n \"claude-opus-4-5\",\\\r\n ],\r\n \"authorization\": \"x-api-key\",\r\n \"compatibility\": {\r\n \"anthropic_messages\": true,\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\nIf you omit `apikey`, Aperture logs a warning at startup but continues to run. Most providers require an API key for authentication, so add one unless your provider handles authentication differently.\r\n\r\nThe `apikey` field requires an API key from the provider's developer platform. Consumer and business subscription plans (such as [Claude Pro or Claude Max](https://www.anthropic.com/pricing), [ChatGPT Plus, Pro, or Team](https://openai.com/chatgpt/pricing), or [Gemini Advanced](https://gemini.google.com/)) do not provide API keys and are not compatible with Aperture.\r\n\r\n## [Default configuration](https://tailscale.com/docs/aperture/configuration\\#default-configuration)\r\n\r\nNew Aperture instances use a default configuration that includes OpenAI and Anthropic providers with common models. The default grants all users access to all models. The following shows the default configuration:\r\n\r\n```json\r\n{\r\n // The grants section uses the Tailscale ACL grant structure.\r\n \"grants\": [\\\r\n // Grant admin access (permission to see the settings and all other\\\r\n // users in the dashboard).\\\r\n {\\\r\n \"src\": [\\\r\n // Explicitly identify certain users by their Tailscale login.\\\r\n \"example-user@example.com\",\\\r\n\\\r\n // Grant admin access to everyone by default.\\\r\n // Remove this after you've configured explicit admin\\\r\n // access for yourself.\\\r\n // BE CAREFUL! If you remove this without granting explicit\\\r\n // admin access to yourself, you'll lose your ability\\\r\n // to edit this file.\\\r\n \"*\",\\\r\n ],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/aperture\": [\\\r\n { \"role\": \"admin\" },\\\r\n ],\\\r\n },\\\r\n },\\\r\n\\\r\n // Every user who can access Aperture gets at least user-level access.\\\r\n // Remove this and Aperture denies access entirely by default.\\\r\n // Admin access in a separate grant takes precedence over this section.\\\r\n {\\\r\n \"src\": [\"*\"],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/aperture\": [\\\r\n { \"role\": \"user\" },\\\r\n ],\\\r\n },\\\r\n },\\\r\n\\\r\n // Default: allow all users to access all models from all providers.\\\r\n // Without this grant, users can't access any models (deny by default).\\\r\n {\\\r\n \"src\": [\"*\"],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/aperture\": [\\\r\n { \"models\": \"**\" },\\\r\n ],\\\r\n },\\\r\n },\\\r\n\\\r\n // This example hook sends traffic to Oso if it matches certain\\\r\n // parameters. Configure Oso in the \"hooks\" section for this to work.\\\r\n {\\\r\n \"src\": [\\\r\n // No users by default. Try \"*\" to capture everyone's traffic.\\\r\n ],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/aperture\": [\\\r\n {\\\r\n \"send_hooks\": [\\\r\n {\\\r\n \"name\": \"oso\",\\\r\n // Capturing only tool calls\\\r\n \"events\": [\"tool_call_entire_request\"],\\\r\n \"send\": [\"user_message\", \"tools\", \"request_body\", \"response_body\"],\\\r\n },\\\r\n ],\\\r\n },\\\r\n ],\\\r\n },\\\r\n },\\\r\n ],\r\n\r\n // Configure your LLM backends here.\r\n // Fill your API keys in below to share these providers with your team.\r\n // There's no limit to the number of providers you can configure.\r\n \"providers\": {\r\n \"openai\": {\r\n \"baseurl\": \"https://api.openai.com\",\r\n \"name\": \"OpenAI\",\r\n \"apikey\": \"YOUR_OPENAI_API_KEY\",\r\n \"models\": [\\\r\n \"gpt-5\",\\\r\n \"gpt-5-mini\",\\\r\n \"gpt-5-nano\",\\\r\n \"gpt-4.1\",\\\r\n \"gpt-4.1-nano\",\\\r\n \"gpt-5.1-codex\",\\\r\n \"gpt-5.1-codex-max\",\\\r\n ],\r\n \"compatibility\": {\r\n \"openai_chat\": true,\r\n \"openai_responses\": true,\r\n \"anthropic_messages\": false,\r\n },\r\n },\r\n \"anthropic\": {\r\n \"baseurl\": \"https://api.anthropic.com\",\r\n \"name\": \"Anthropic\",\r\n \"apikey\": \"YOUR_ANTHROPIC_API_KEY\",\r\n \"models\": [\\\r\n \"claude-sonnet-4-5\",\\\r\n \"claude-sonnet-4-5-20250929\",\\\r\n \"claude-haiku-4-5\",\\\r\n \"claude-haiku-4-5-20251001\",\\\r\n \"claude-opus-4-5\",\\\r\n \"claude-opus-4-5-20251101\",\\\r\n ],\r\n \"compatibility\": {\r\n \"openai_chat\": false,\r\n \"openai_responses\": false,\r\n \"anthropic_messages\": true,\r\n },\r\n },\r\n },\r\n\r\n // Hooks are configured API endpoints that Aperture calls under certain\r\n // conditions. The conditions themselves are configured in the\r\n // \"grants\" section.\r\n \"hooks\": {\r\n \"oso\": {\r\n \"url\": \"https://api.osohq.com/api/agents/v1/model-request\",\r\n \"apikey\": \"YOUR_OSO_API_KEY\",\r\n },\r\n },\r\n}\r\n```\r\n\r\n## [Configuration reference](https://tailscale.com/docs/aperture/configuration\\#configuration-reference)\r\n\r\nThe Aperture configuration contains several top-level sections that control different aspects of Aperture's behavior. The following table describes the available top-level sections:\r\n\r\n| Section | Required | Description |\r\n| --- | --- | --- |\r\n| `providers` | Yes | Map of LLM provider configurations. |\r\n| `grants` | No | Access control policies for users, models, and quotas. Uses the Tailscale grant structure. |\r\n| `quotas` | No | Dollar-based spending limits using token buckets. |\r\n| `hooks` | No | Webhook endpoint configurations. |\r\n| `exporters` | No | LLM session log export configuration. Currently supports S3-compatible storage. |\r\n| `auto_cost_basis` | No | Boolean (default `true`). When `true`, Aperture infers `cost_basis` from a provider's compatibility flags when no explicit `cost_basis` is set. Set to `false` to disable auto-inference, so only providers with an explicit `cost_basis` produce cost estimates. |\r\n\r\n### [`providers`](https://tailscale.com/docs/aperture/configuration\\#providers)\r\n\r\nThe `providers` section specifies the LLM providers to which Aperture routes requests. A unique string key identifies each provider. The following example shows the basic structure:\r\n\r\n```json\r\n{\r\n \"providers\": {\r\n \"openai\": { ... },\r\n \"anthropic\": { ... },\r\n \"private\": { ... }\r\n }\r\n}\r\n```\r\n\r\nEach provider configuration accepts the following fields:\r\n\r\n| Field | Type | Required | Default | Description |\r\n| --- | --- | --- | --- | --- |\r\n| `baseurl` | string | Yes | N/A | Base URL for the provider's API. |\r\n| `models` | array | Yes | N/A | List of model IDs available from this provider. |\r\n| `apikey` | string | No | `\"\"` | API key for authentication. |\r\n| `authorization` | string | No | `\"bearer\"` | Authorization header type. |\r\n| `name` | string | No | `\"\"` | Display name for the UI. |\r\n| `description` | string | No | `\"\"` | Description shown in the UI. |\r\n| `compatibility` | object | No | `openai_chat` enabled, all others disabled | API compatibility flags. Refer to the [provider compatibility reference](https://tailscale.com/docs/aperture/provider-compatibility) for details. |\r\n| `cost_basis` | string | No | Auto-inferred | Override the pricing service used for cost estimation. Refer to the [provider compatibility reference](https://tailscale.com/docs/aperture/provider-compatibility) for valid values. |\r\n| `preference` | int | No | `0` | Routing priority when a model is available from multiple providers. Higher value wins. |\r\n| `disabled` | bool | No | `false` | Deactivates the provider without removing its configuration. Disabled providers are excluded from routing and `/v1/models`. |\r\n| `add_headers` | array | No | `[]` | Custom headers added to every upstream request for this provider. Each entry uses `\"Header-Name: value\"` format. |\r\n| `model_cost_map` | array | No | `[]` | Map unknown model names to known models for pricing. Refer to [model cost map](https://tailscale.com/docs/aperture/provider-compatibility#model-cost-map). |\r\n\r\nThe `authorization` field is not required for all providers. For example, Vertex AI uses a service account key file instead of an API key (prefixed with `keyfile::`). Refer to [set up a Vertex AI provider](https://tailscale.com/docs/aperture/how-to/use-vertex-ai) for step-by-step configuration instructions.\r\n\r\n#### [Authorization types](https://tailscale.com/docs/aperture/configuration\\#authorization-types)\r\n\r\nDifferent providers require different authorization header formats. The `authorization` field supports `bearer` (default, used by OpenAI and most providers), `x-api-key` (Anthropic), and `x-goog-api-key` (Google Gemini). For the full authorization types table and provider-specific details, refer to the [provider compatibility reference](https://tailscale.com/docs/aperture/provider-compatibility).\r\n\r\n#### [Provider compatibility](https://tailscale.com/docs/aperture/configuration\\#provider-compatibility)\r\n\r\nThe `compatibility` object specifies which API formats the provider supports. This determines which endpoints Aperture exposes for the provider's models. Flags include `openai_chat` (default enabled), `openai_responses`, `anthropic_messages`, `gemini_generate_content`, `bedrock_model_invoke`, and others. For the complete compatibility flags table, provider matrix, and configuration examples for each provider, refer to the [provider compatibility reference](https://tailscale.com/docs/aperture/provider-compatibility).\r\n\r\n#### [Provider examples](https://tailscale.com/docs/aperture/configuration\\#provider-examples)\r\n\r\nFor complete configuration examples for each supported provider (OpenAI, Anthropic, Google Gemini, Vertex AI, Amazon Bedrock, OpenRouter, and self-hosted LLMs), refer to the [provider compatibility reference](https://tailscale.com/docs/aperture/provider-compatibility).\r\n\r\n### [Pricing and cost estimation](https://tailscale.com/docs/aperture/configuration\\#pricing-and-cost-estimation)\r\n\r\nAperture estimates the dollar cost of every LLM request. Cost estimates power quotas, hook metadata, and the per-model pricing shown in the Aperture dashboard. Aperture auto-infers pricing for known providers based on compatibility flags, but you can override this with the `cost_basis` and `model_cost_map` provider fields. For the full list of `cost_basis` values, model cost mapping syntax, and per-provider pricing details, refer to the [provider compatibility reference](https://tailscale.com/docs/aperture/provider-compatibility).\r\n\r\nAperture surfaces cost data in several places:\r\n\r\n- **Models** page of the Aperture dashboard: Each model shows per-million-token pricing (input/output) with a tooltip that includes cache, reasoning, image, and web search rates.\r\n- **CSV export**: The **Adoption** page's **Download CSV** button exports usage data including token counts per model, user, and date.\r\n- **Hooks**: Include `\"estimated_cost\"` in a hook's `send` array to receive dollar cost, cost basis, and token usage with every hook call. Refer to [hook send types](https://tailscale.com/docs/aperture/configuration#hook-send-types) for details.\r\n\r\n### [`grants`](https://tailscale.com/docs/aperture/configuration\\#grants)\r\n\r\nThe `grants` section specifies access control policies that determine which users can access which models, what hooks fire, and which quotas apply. Grants use the [Tailscale grant structure](https://tailscale.com/docs/features/access-control/grants/grants-app-capabilities) with capabilities scoped under `\"tailscale.com/cap/aperture\"`. Aperture is deny-by-default: without a matching grant, a user cannot access any models.\r\n\r\nFor step-by-step instructions on configuring access, refer to [Control model access](https://tailscale.com/docs/aperture/how-to/grant-model-access) and [Set up admin access](https://tailscale.com/docs/aperture/how-to/set-up-admin-access).\r\n\r\nThe `grants` section replaces the deprecated `temp_grants` syntax with a new structure. The `temp_grants` syntax still works but is not recommended for new configurations.\r\n\r\nYou can specify grants in two places:\r\n\r\n1. **Aperture configuration**: In the `\"grants\"` array (described below).\r\n2. **Tailnet policy file**: As app capabilities under `\"tailscale.com/cap/aperture\"`, delivered to Aperture automatically through the Tailscale coordination server.\r\n\r\nAperture merges grants from both sources additively. Roles escalate (user to admin) but never downgrade.\r\n\r\n#### [Basic structure](https://tailscale.com/docs/aperture/configuration\\#basic-structure)\r\n\r\nA grant specifies a source (`src`) and a set of app capabilities:\r\n\r\n```json\r\n\"grants\": [\\\r\n {\\\r\n \"src\": [\"*\"], // who this grant applies to\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/aperture\": [\\\r\n // array of individual capabilities\\\r\n { \"models\": \"**\" }, // allow access to all models\\\r\n ],\\\r\n },\\\r\n },\\\r\n]\r\n```\r\n\r\n#### [Source match (`src`)](https://tailscale.com/docs/aperture/configuration\\#source-match-src)\r\n\r\nThe `src` field determines which users a grant applies to:\r\n\r\n- `\"*\"`: Matches everyone.\r\n- `\"alice@example.com\"`: Matches a specific Tailscale login name.\r\n- `\"(loopback)\"`: Matches local/loopback requests (useful for development).\r\n\r\n#### [Model access](https://tailscale.com/docs/aperture/configuration\\#model-access)\r\n\r\nEach `models` field accepts a single glob pattern using fully-qualified `provider/model` format. To match multiple providers, use separate grant entries.\r\n\r\n| Pattern | Matches |\r\n| --- | --- |\r\n| `\"**\"` | All models from all providers |\r\n| `\"anthropic/**\"` | All Anthropic models |\r\n| `\"openai/gpt-5\"` | Exactly `openai/gpt-5` |\r\n| `\"*/claude-sonnet*\"` | Any `claude-sonnet*` model from any single provider |\r\n| `\"aperture-*/**\"` | Any model from a provider whose name starts with `aperture-` |\r\n\r\n`*` matches a single path segment. `**` matches zero or more segments.\r\n\r\nA grant with no `models` field is \"floating,\" meaning it applies globally (useful for hooks and quotas that apply regardless of model).\r\n\r\n#### [Role assignment](https://tailscale.com/docs/aperture/configuration\\#role-assignment)\r\n\r\nRoles determine a user's permission level:\r\n\r\n```json\r\n{ \"role\": \"admin\" } // full admin access\r\n{ \"role\": \"user\" } // standard user access\r\n```\r\n\r\nWithout a role grant, the user cannot access Aperture. If multiple grants match a given user, the highest-permissioned role (admin) wins.\r\n\r\n#### [MCP access](https://tailscale.com/docs/aperture/configuration\\#mcp-access)\r\n\r\nAperture's MCP server support is experimental. The MCP grants syntax may change.\r\n\r\nGrant access to registered MCP items in the same way as models:\r\n\r\n```json\r\n{\r\n \"mcp_tools\": \"local/*\", // tools from the \"local\" MCP server\r\n \"mcp_resources\": \"**\", // all resources from all servers\r\n \"mcp_templates\": \"remote/*\", // templates from \"remote\" server\r\n}\r\n```\r\n\r\n#### [Additional capability fields](https://tailscale.com/docs/aperture/configuration\\#additional-capability-fields)\r\n\r\nEach capability object in the `tailscale.com/cap/aperture` array can also include these fields:\r\n\r\n| Field | Type | Description |\r\n| --- | --- | --- |\r\n| `add_headers` | array | Custom headers prepended to upstream requests when this grant matches. Each entry uses `\"Header-Name: value\"` format. |\r\n| `enable_chat_ui` | bool | Grants access to the chat UI feature. |\r\n| `read_metrics` | bool | Grants access to the `/metrics` Prometheus endpoint. |\r\n\r\n#### [Custom app capabilities](https://tailscale.com/docs/aperture/configuration\\#custom-app-capabilities)\r\n\r\nGrants can include capability keys beyond `tailscale.com/cap/aperture`. Aperture passes these through to hooks when you include the `\"grants\"` send type:\r\n\r\n```json\r\n{\r\n \"src\": [\"admin@example.com\"],\r\n \"app\": {\r\n \"tailscale.com/cap/aperture\": [\\\r\n { \"role\": \"admin\" },\\\r\n { \"models\": \"**\" },\\\r\n ],\r\n // Custom capability — forwarded to hooks via \"grants\" send type\r\n \"mycompany.com/cap/policy\": [\\\r\n { \"tier\": \"enterprise\", \"department\": \"engineering\" },\\\r\n ],\r\n },\r\n},\r\n```\r\n\r\nWhen a hook includes `\"grants\"` in its `send` array, these custom capabilities appear in the hook metadata. External systems can use these capabilities to make authorization decisions.\r\n\r\n#### [Grants from the tailnet policy file](https://tailscale.com/docs/aperture/configuration\\#grants-from-the-tailnet-policy-file)\r\n\r\nSpecify grants directly in the tailnet policy file to use Tailscale's groups, tags, and device postures. This is the recommended approach for organizations that already manage access through Tailscale:\r\n\r\n```json\r\n// In the tailnet policy file (not the Aperture config):\r\n\"grants\": [\\\r\n {\\\r\n \"src\": [\"group:engineering\"],\\\r\n \"dst\": [\"tag:aperture\"],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/aperture\": [\\\r\n { \"models\": \"**\" },\\\r\n { \"role\": \"user\" },\\\r\n ],\\\r\n },\\\r\n },\\\r\n {\\\r\n \"src\": [\"group:ml-team\"],\\\r\n \"dst\": [\"tag:aperture\"],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/aperture\": [\\\r\n { \"models\": \"**\" },\\\r\n { \"role\": \"admin\" },\\\r\n ],\\\r\n },\\\r\n },\\\r\n]\r\n```\r\n\r\nAperture receives these capabilities from the Tailscale peer information at request time and merges them with any grants specified in the Aperture configuration.\r\n\r\nYou can also scope grants based on Tailscale device postures. For example, grant access to different models or quotas, or apply different hooks, based on whether a user is on a managed corporate laptop versus an unmanaged VM (virtual machine).\r\n\r\nGroups (for example, `group:engineering`) aren't available for grants specified in the Aperture configuration. The Tailscale coordination server tracks group membership information and does not share it with Aperture. Grants specified in the Aperture configuration can match on individual login names or tags.\r\n\r\n### [`quotas`](https://tailscale.com/docs/aperture/configuration\\#quotas)\r\n\r\nThe `quotas` section specifies dollar-based spending limits using token buckets. Each bucket has a capacity (maximum balance) and a refill rate. When a request's estimated cost would bring a bucket below zero, Aperture rejects the request with HTTP 429.\r\n\r\nFor step-by-step instructions, refer to [Set per-user spending limits](https://tailscale.com/docs/aperture/how-to/set-per-user-spending-limits) and [Set a team-wide budget](https://tailscale.com/docs/aperture/how-to/set-team-budget). To check and refill budgets, refer to [Check and refill budgets](https://tailscale.com/docs/aperture/how-to/check-and-refill-budgets).\r\n\r\n```json\r\n\"quotas\": {\r\n // Per-user daily budget: refills $5/day, can burst up to $10\r\n \"daily:\": {\r\n \"capacity\": \"$10.00\",\r\n \"rate\": \"$5.00/day\",\r\n \"on_exceed\": \"reject\",\r\n },\r\n\r\n // Shared pool across all users who reference it\r\n \"eng-team-pool\": {\r\n \"capacity\": \"$100.00\",\r\n \"rate\": \"$100.00/day\",\r\n \"on_exceed\": \"reject\",\r\n },\r\n\r\n // Per-user limit for expensive models\r\n \"opus:\": {\r\n \"capacity\": \"$5.00\",\r\n \"rate\": \"$2.50/day\",\r\n \"on_exceed\": \"reject\",\r\n },\r\n}\r\n```\r\n\r\nEach quota accepts the following fields:\r\n\r\n| Field | Format | Description |\r\n| --- | --- | --- |\r\n| `capacity` | `\"$\"` | Maximum balance the bucket can hold. Also the starting balance. |\r\n| `rate` | `\"$/\"` | How fast the bucket refills. Units: `min`, `hour`, `day`, `week`, `month` (30 days). |\r\n| `on_exceed` | `\"reject\"` | Action when the bucket is empty. The supported value is `\"reject\"` (HTTP 429). |\r\n\r\n#### [Template variables](https://tailscale.com/docs/aperture/configuration\\#template-variables)\r\n\r\nQuota names can include template variables that expand at request time:\r\n\r\n| Template | Expands to | Example |\r\n| --- | --- | --- |\r\n| `` | Caller's Tailscale login name or tag combination | `daily:` expands to `daily:alice@example.com` |\r\n| `` | Caller's node ID (a distinct quota for each node, even if nodes share the same user or tag) | `device:` expands to `device:nXXXXXXXXXCNTRL` |\r\n\r\nQuotas without a template variable (for example, `eng-team-pool`) create a single shared bucket.\r\n\r\n#### [Attach quotas to grants](https://tailscale.com/docs/aperture/configuration\\#attach-quotas-to-grants)\r\n\r\nQuotas take effect only when attached to grants. A quota specified in the `quotas` section does nothing until a grant references it. When a request matches a grant, all quotas listed in that grant are charged at the same time:\r\n\r\n```json\r\n\"grants\": [\\\r\n {\\\r\n \"src\": [\"*\"],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/aperture\": [\\\r\n {\\\r\n \"models\": \"**\",\\\r\n \"quotas\": [\\\r\n {\"bucket\": \"daily:\"},\\\r\n {\"bucket\": \"eng-team-pool\"},\\\r\n ],\\\r\n },\\\r\n ],\\\r\n },\\\r\n },\\\r\n]\r\n```\r\n\r\n#### [How multiple quotas interact](https://tailscale.com/docs/aperture/configuration\\#how-multiple-quotas-interact)\r\n\r\nWhen a grant references multiple quota buckets, all buckets must have a positive balance for the request to proceed. If any single bucket is exhausted, Aperture rejects the request, even if other buckets have remaining balance.\r\n\r\nAfter the response completes, Aperture deducts the estimated cost from every referenced bucket at the same time.\r\n\r\nA request can match multiple grants, each with their own quotas. Aperture collects and enforces all matching quotas together.\r\n\r\n#### [Quota examples](https://tailscale.com/docs/aperture/configuration\\#quota-examples)\r\n\r\nThe following examples show common quota configurations.\r\n\r\n##### [Per-user quota](https://tailscale.com/docs/aperture/configuration\\#per-user-quota)\r\n\r\nEach user gets their own bucket with independent capacity and refill rate:\r\n\r\n```json\r\n\"quotas\": {\r\n \"daily:\": {\r\n \"capacity\": \"$10.00\",\r\n \"rate\": \"$5.00/day\",\r\n \"on_exceed\": \"reject\",\r\n },\r\n},\r\n\"grants\": [\\\r\n {\\\r\n \"src\": [\"*\"],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/aperture\": [\\\r\n { \"role\": \"user\" },\\\r\n { \"models\": \"**\",\\\r\n \"quotas\": [{\"bucket\": \"daily:\"}] },\\\r\n ],\\\r\n },\\\r\n },\\\r\n]\r\n```\r\n\r\nThis creates a separate bucket for each user (for example, `daily:alice@example.com`, `daily:bob@example.com`), each with $10 capacity and a $5/day refill.\r\n\r\n##### [Quota scoped to specific models](https://tailscale.com/docs/aperture/configuration\\#quota-scoped-to-specific-models)\r\n\r\nApply a quota only when the request targets specific models:\r\n\r\n```json\r\n\"quotas\": {\r\n \"opus:\": {\r\n \"capacity\": \"$5.00\",\r\n \"rate\": \"$2.50/day\",\r\n \"on_exceed\": \"reject\",\r\n },\r\n},\r\n\"grants\": [\\\r\n {\\\r\n \"src\": [\"*\"],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/aperture\": [\\\r\n // General access — no quota\\\r\n { \"models\": \"**\" },\\\r\n // Additional quota for Opus models only\\\r\n {\\\r\n \"models\": \"*/claude-opus*\",\\\r\n \"quotas\": [{\"bucket\": \"opus:\"}],\\\r\n },\\\r\n ],\\\r\n },\\\r\n },\\\r\n]\r\n```\r\n\r\nThe `opus:` quota applies only when the request targets an Opus model. Other models are unmetered.\r\n\r\n##### [Combine per-user and shared quotas](https://tailscale.com/docs/aperture/configuration\\#combine-per-user-and-shared-quotas)\r\n\r\nCharge each request against both a personal budget and a shared team pool:\r\n\r\n```json\r\n\"quotas\": {\r\n \"daily:\": {\r\n \"capacity\": \"$10.00\",\r\n \"rate\": \"$5.00/day\",\r\n \"on_exceed\": \"reject\",\r\n },\r\n \"team-pool\": {\r\n \"capacity\": \"$200.00\",\r\n \"rate\": \"$200.00/day\",\r\n \"on_exceed\": \"reject\",\r\n },\r\n},\r\n\"grants\": [\\\r\n {\\\r\n \"src\": [\"*\"],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/aperture\": [\\\r\n { \"role\": \"user\" },\\\r\n {\\\r\n \"models\": \"**\",\\\r\n \"quotas\": [\\\r\n {\"bucket\": \"daily:\"},\\\r\n {\"bucket\": \"team-pool\"},\\\r\n ],\\\r\n },\\\r\n ],\\\r\n },\\\r\n },\\\r\n]\r\n```\r\n\r\nEvery request deducts from both the user's personal bucket and the shared team pool. Aperture blocks a user who exhausts their $10 daily limit even if the team pool has remaining budget.\r\n\r\n### [`hooks`](https://tailscale.com/docs/aperture/configuration\\#hooks)\r\n\r\nThe `hooks` section specifies webhook endpoints that Aperture calls when conditions match. A unique string key identifies each hook, and grants reference this key. For step-by-step setup, refer to [Build a custom webhook](https://tailscale.com/docs/aperture/how-to/build-custom-webhook). For integration-specific guides, refer to [Integrate Oso with Aperture](https://tailscale.com/docs/aperture/how-to/integrate-oso) or [Integrate Cerbos with Aperture](https://tailscale.com/docs/aperture/how-to/integrate-cerbos).\r\n\r\nThe following example shows the hooks configuration:\r\n\r\n```json\r\n{\r\n \"hooks\": {\r\n \"oso\": {\r\n \"url\": \"https://api.osohq.com/api/agents/v1/model-request\",\r\n \"apikey\": \"YOUR_OSO_API_KEY\",\r\n \"timeout\": \"10s\"\r\n },\r\n \"my-webhook\": {\r\n \"url\": \"https://example.com/webhook\",\r\n \"apikey\": \"YOUR_API_KEY\"\r\n }\r\n }\r\n}\r\n```\r\n\r\nEach hook configuration accepts the following fields:\r\n\r\n| Field | Type | Required | Default | Description |\r\n| --- | --- | --- | --- | --- |\r\n| `url` | string | Yes | N/A | HTTP or HTTPS endpoint to POST hook data to. |\r\n| `apikey` | string | No | `\"\"` | API key that Aperture sends to the hook endpoint using the method specified by `authorization`. |\r\n| `authorization` | string | No | `\"bearer\"` | How Aperture sends the API key. Supports the same values as provider authorization: `bearer`, `x-api-key`, `x-goog-api-key`. |\r\n| `timeout` | string | No | `\"5s\"` | Maximum duration to wait for the hook to respond. |\r\n| `disabled` | boolean | No | `false` | Skips this hook when Aperture would otherwise call it. Useful for temporarily disabling a hook without removing its configuration. |\r\n\r\nThe `timeout` field accepts Go duration strings such as `5s`, `30s`, or `1m`. Set to `0` to disable the timeout.\r\n\r\nThe `send_hooks` entries in the `grants` section trigger hooks. A hook specified here does nothing until a grant references it.\r\n\r\n### [Hook grants](https://tailscale.com/docs/aperture/configuration\\#hook-grants)\r\n\r\nTo trigger a hook, add a `send_hooks` entry to a capability in the `grants` section. Hook grants specify which requests trigger the hook and what data to send.\r\n\r\n```json\r\n{\r\n \"grants\": [\\\r\n {\\\r\n \"src\": [\"*\"],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/aperture\": [\\\r\n {\\\r\n \"models\": \"**\",\\\r\n \"send_hooks\": [\\\r\n {\\\r\n \"name\": \"oso\",\\\r\n \"events\": [\"tool_call_entire_request\"],\\\r\n \"send\": [\"tools\", \"user_message\", \"request_body\", \"response_body\"],\\\r\n },\\\r\n ],\\\r\n },\\\r\n ],\\\r\n },\\\r\n },\\\r\n ]\r\n}\r\n```\r\n\r\nEach `send_hooks` entry contains the following fields:\r\n\r\n| Field | Type | Description |\r\n| --- | --- | --- |\r\n| `name` | string | Key referencing a hook specified in the top-level `hooks` section. |\r\n| `events` | array | Event types that trigger the hook. |\r\n| `send` | array | List of data types to include in the hook payload. |\r\n\r\n#### [Hook events](https://tailscale.com/docs/aperture/configuration\\#hook-events)\r\n\r\n| Event | Description |\r\n| --- | --- |\r\n| `tool_call_entire_request` | Fires once after the response completes if any message in the response contained tool calls. |\r\n| `entire_request` | Fires for every completed request. |\r\n\r\n#### [Hook send types](https://tailscale.com/docs/aperture/configuration\\#hook-send-types)\r\n\r\nThe `send` array specifies which data to include in the POST payload sent to the hook endpoint:\r\n\r\n| Field | Description |\r\n| --- | --- |\r\n| `tools` | Array of tool calls extracted from the response. |\r\n| `request_body` | The original request body sent to the LLM. |\r\n| `user_message` | The user's message from the request. |\r\n| `response_body` | The reconstructed response body JSON. |\r\n| `raw_responses` | Array of raw SSE messages (for streaming) or single response object. |\r\n| `estimated_cost` | Dollar cost estimate, pricing basis, and token usage breakdown. |\r\n| `grants` | Non-Aperture app capabilities from the user's grants (custom capabilities). |\r\n| `quotas` | Current state of all quota buckets that applied to this request. |\r\n\r\n#### [`estimated_cost`](https://tailscale.com/docs/aperture/configuration\\#estimated_cost)\r\n\r\nIncludes the dollar cost estimate, the pricing basis used, and a token usage breakdown. These fields appear inside the `metadata` object of the hook payload:\r\n\r\n```json\r\n{\r\n \"models\": \"**\",\r\n \"send_hooks\": [\\\r\n {\\\r\n \"name\": \"audit\",\\\r\n \"events\": [\"tool_call_entire_request\"],\\\r\n \"send\": [\"tools\", \"estimated_cost\"],\\\r\n },\\\r\n ],\r\n}\r\n```\r\n\r\nThe hook receives the cost data inside `metadata`:\r\n\r\n```json\r\n{\r\n \"metadata\": {\r\n \"login_name\": \"user@example.com\",\r\n \"...\": \"...\",\r\n \"estimated_cost\": {\r\n \"dollars\": 0.0342,\r\n \"cost_basis\": \"anthropic/claude-sonnet-4-5\",\r\n \"usage\": {\r\n \"input_tokens\": 1500,\r\n \"output_tokens\": 800,\r\n \"cached_tokens\": 200,\r\n \"reasoning_tokens\": 0\r\n }\r\n }\r\n },\r\n \"tool_calls\": [...]\r\n}\r\n```\r\n\r\n#### [`grants`](https://tailscale.com/docs/aperture/configuration\\#grants-1)\r\n\r\nIncludes any non-Aperture app capabilities from the user's grants. This lets external systems (policy engines, audit logs) access custom capabilities attached to the user. The `grants` data appears inside the `metadata` object:\r\n\r\n```json\r\n{\r\n \"src\": [\"alice@example.com\"],\r\n \"app\": {\r\n \"tailscale.com/cap/aperture\": [\\\r\n { \"models\": \"**\" },\\\r\n {\\\r\n \"send_hooks\": [\\\r\n {\\\r\n \"name\": \"policy-engine\",\\\r\n \"events\": [\"entire_request\"],\\\r\n \"send\": [\"estimated_cost\", \"grants\"],\\\r\n },\\\r\n ],\\\r\n },\\\r\n ],\r\n \"mycompany.com/cap/policy\": [\\\r\n {\"tier\": \"enterprise\", \"max_context\": 200000},\\\r\n ],\r\n },\r\n}\r\n```\r\n\r\nThe hook receives the custom capabilities inside `metadata`:\r\n\r\n```json\r\n{\r\n \"metadata\": {\r\n \"login_name\": \"alice@example.com\",\r\n \"...\": \"...\",\r\n \"grants\": {\r\n \"mycompany.com/cap/policy\": [\\\r\n {\"tier\": \"enterprise\", \"max_context\": 200000}\\\r\n ]\r\n },\r\n \"estimated_cost\": { \"...\" }\r\n }\r\n}\r\n```\r\n\r\n#### [`quotas`](https://tailscale.com/docs/aperture/configuration\\#quotas-1)\r\n\r\nIncludes the current state of all quota buckets that applied to the request. The `quotas` data appears inside the `metadata` object:\r\n\r\n```json\r\n\"send\": [\"tools\", \"quotas\"]\r\n```\r\n\r\nThe hook receives the bucket state inside `metadata`:\r\n\r\n```json\r\n{\r\n \"metadata\": {\r\n \"login_name\": \"alice@example.com\",\r\n \"...\": \"...\",\r\n \"quotas\": {\r\n \"daily:alice@example.com\": {\r\n \"current\": 7250000000,\r\n \"capacity\": 10000000000,\r\n \"rate\": \"$5.00/day\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\nValues for `current` and `capacity` are in nanodollars (1 dollar = 1,000,000,000 nanodollars).\r\n\r\nEvery hook call automatically includes a `metadata` object with request context:\r\n\r\n```json\r\n{\r\n \"metadata\": {\r\n \"login_name\": \"user@example.com\",\r\n \"user_agent\": \"curl/8.0\",\r\n \"url\": \"/v1/chat/completions\",\r\n \"model\": \"gpt-5\",\r\n \"provider\": \"openai\",\r\n \"tailnet_name\": \"example.com\",\r\n \"stable_node_id\": \"n12345\",\r\n \"request_id\": \"abc123\",\r\n \"session_id\": \"oacc_1a2b3c4d5e6f7890\"\r\n }\r\n}\r\n```\r\n\r\n#### [Hook grant example](https://tailscale.com/docs/aperture/configuration\\#hook-grant-example)\r\n\r\nThe following example sends tool call data and cost estimates to an audit service for all requests from a specific user:\r\n\r\n```json\r\n{\r\n \"grants\": [\\\r\n {\\\r\n \"src\": [\"developer@company.com\"],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/aperture\": [\\\r\n {\\\r\n \"models\": \"anthropic/**\",\\\r\n \"send_hooks\": [\\\r\n {\\\r\n \"name\": \"my-webhook\",\\\r\n \"events\": [\"tool_call_entire_request\"],\\\r\n \"send\": [\"tools\", \"user_message\", \"estimated_cost\"],\\\r\n },\\\r\n ],\\\r\n },\\\r\n {\\\r\n \"models\": \"openai/**\",\\\r\n \"send_hooks\": [\\\r\n {\\\r\n \"name\": \"my-webhook\",\\\r\n \"events\": [\"tool_call_entire_request\"],\\\r\n \"send\": [\"tools\", \"user_message\", \"estimated_cost\"],\\\r\n },\\\r\n ],\\\r\n },\\\r\n ],\\\r\n },\\\r\n },\\\r\n ]\r\n}\r\n```\r\n\r\n### [`exporters`](https://tailscale.com/docs/aperture/configuration\\#exporters)\r\n\r\nThe `exporters` section configures periodic export of LLM session logs to external storage. Currently, Aperture supports exporting to S3-compatible storage (AWS S3, Google Cloud Storage, MinIO, Backblaze B2, and others). For step-by-step setup, refer to [Export usage data to S3](https://tailscale.com/docs/aperture/how-to/export-usage-data-to-s3).\r\n\r\nThe following example shows the exporters configuration:\r\n\r\n```json\r\n{\r\n \"exporters\": {\r\n \"s3\": {\r\n \"endpoint\": \"https://your-s3-compatible-endpoint.url\",\r\n \"bucket_name\": \"aperture-exports\",\r\n \"region\": \"us-east-1\",\r\n \"prefix\": \"prod\",\r\n \"access_key_id\": \"YOUR_AWS_KEY\",\r\n \"access_secret\": \"YOUR_AWS_SECRET\",\r\n \"every\": 3600,\r\n \"limit\": 1000\r\n }\r\n }\r\n}\r\n```\r\n\r\nSetting `bucket_name` to a non-empty value enables the S3 exporter. Each S3 exporter configuration accepts the following fields:\r\n\r\n| Field | Type | Required | Default | Description |\r\n| --- | --- | --- | --- | --- |\r\n| `endpoint` | string | No | `\"\"` | HTTP endpoint for an S3-compatible API. Required for non-AWS services (GCS, MinIO, Backblaze B2). Omit for Amazon S3, where Aperture infers the endpoint from `region`. |\r\n| `bucket_name` | string | Conditional | `null` | Name of the S3 bucket to upload exports to. Setting this field to a non-empty value enables the S3 exporter. |\r\n| `region` | string | No | `\"us-east-1\"` | AWS region for the bucket. Required even for non-AWS endpoints because the AWS SDK validates this field. |\r\n| `prefix` | string | No | `\"\"` | Path prefix for new S3 objects. Must not end with `/`. |\r\n| `access_key_id` | string | Conditional | `null` | AWS access key ID used to authenticate. Required and must be non-empty when `bucket_name` is set and static credentials are used. |\r\n| `access_secret` | string | Conditional | `null` | Secret key used with `access_key_id` to authenticate. Required and must be non-empty when `access_key_id` is set. |\r\n| `every` | int | No | `3600` | Number of seconds to wait after the last export before starting another. Default is one hour. |\r\n| `limit` | int | No | `1000` | Maximum number of records per export. Aperture caps this value at `2500` and silently reduces higher values. |\r\n\r\n### [MCP](https://tailscale.com/docs/aperture/configuration\\#mcp)\r\n\r\nAperture's MCP server support is experimental. The MCP configuration syntax may change.\r\n\r\nThe `mcp` section configures MCP (Model Context Protocol) server proxying. Aperture connects to remote MCP servers, aggregates their tools, resources, and resource templates, and exposes them through a single `/v1/mcp` endpoint. Refer to [MCP server proxying](https://tailscale.com/docs/aperture/how-to/mcp-server) for setup instructions and troubleshooting.\r\n\r\n```json\r\n{\r\n \"mcp\": {\r\n \"accept_registrations\": true,\r\n \"servers\": {\r\n \"local\": {\r\n \"url\": \"http://localhost:8185/v1/mcp\"\r\n },\r\n \"remote\": {\r\n \"url\": \"http://mcp-server.example.ts.net:8080/v1/mcp\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\n#### [`mcp` fields](https://tailscale.com/docs/aperture/configuration\\#mcp-fields)\r\n\r\n| Field | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| `accept_registrations` | boolean | `false` | Allow backends to register dynamically through `POST /v1/mcp/register`. Backends POST `{\"url\": \"http://...\"}` and keep the connection open. Tools are unregistered when the connection closes. |\r\n| `servers` | map | `{}` | Map of server ID to server configuration. The map key is the server ID, which becomes the name prefix for tools (`serverID_toolname`), resources (`serverID-uri`), and resource templates (`serverID-uriTemplate`) from that backend. |\r\n\r\n#### [`servers` fields](https://tailscale.com/docs/aperture/configuration\\#servers-fields)\r\n\r\nEach entry in the `servers` map accepts the following fields:\r\n\r\n| Field | Type | Required | Description |\r\n| --- | --- | --- | --- |\r\n| `url` | string | Yes | The MCP server endpoint URL (for example, `http://localhost:8185/v1/mcp`). |\r\n\r\n## [Quota enforcement](https://tailscale.com/docs/aperture/configuration\\#quota-enforcement)\r\n\r\nAperture enforces quotas at request time by checking all referenced buckets before forwarding a request to the provider.\r\n\r\n### [What happens when a request exceeds a quota](https://tailscale.com/docs/aperture/configuration\\#what-happens-when-a-request-exceeds-a-quota)\r\n\r\nWhen a request would exceed any of its quota buckets, Aperture:\r\n\r\n1. Rejects the request with HTTP status **429 (Too Many Requests)**.\r\n2. Sets a `Retry-After` header with the estimated seconds until enough budget refills.\r\n3. Formats the error to match the provider's native error format.\r\n4. Logs a warning with the bucket detail, login name, and model.\r\n\r\nThe following table describes the provider-specific error formats:\r\n\r\n| Provider | Error format |\r\n| --- | --- |\r\n| Anthropic | `{\"type\":\"error\",\"error\":{\"type\":\"rate_limit_error\",\"message\":\"...\"}}` |\r\n| OpenAI | `{\"error\":{\"message\":\"...\",\"type\":\"insufficient_quota\",\"code\":\"insufficient_quota\"}}` |\r\n| Bedrock | `{\"message\":\"...\"}` with `x-amzn-ErrorType: ThrottlingException` |\r\n| Google/Vertex | `{\"error\":{\"code\":429,\"message\":\"...\",\"status\":\"RESOURCE_EXHAUSTED\"}}` |\r\n\r\n### [Where Aperture logs enforcement](https://tailscale.com/docs/aperture/configuration\\#where-aperture-logs-enforcement)\r\n\r\nAperture logs quota exceeded events at the **Warn** level in the server log with the following fields:\r\n\r\n- `detail`: Which buckets Aperture exhausted.\r\n- `login_name`: The user that Aperture blocked.\r\n- `model`: The `provider/model` that the user requested.\r\n\r\n## [Validation](https://tailscale.com/docs/aperture/configuration\\#validation)\r\n\r\nAperture validates configuration at load time and reports problems. Some issues are fatal errors that prevent the configuration from loading, while others are warnings that let the configuration load but should be addressed. The following table describes the validations.\r\n\r\nAperture handles validation differently depending on how the configuration is loaded:\r\n\r\n- **When Aperture loads configuration at startup or reload**: Aperture logs warnings but loads the configuration successfully. This lets Aperture start even with minor issues.\r\n- **When saving through the API or the Settings page of the Aperture dashboard**: Aperture treats warnings as errors and rejects the save. This ensures that configurations saved through the UI are warning-free.\r\n- **When using the validate endpoint (`POST /aperture/config:validate`)**: Aperture surfaces warnings as validation errors (the response sets `Valid: false`), matching the save behavior.\r\n\r\nThe admin lockout check only applies when saving — it prevents you from accidentally removing your own admin access.\r\n\r\n| Condition | Message | Severity |\r\n| --- | --- | --- |\r\n| No providers or MCP servers | `no providers or mcp servers defined; users will not be able to access any models` | Warning |\r\n| Provider missing `baseurl` | `provider {id} has no baseurl configured` | Warning |\r\n| Invalid `authorization` type | `provider {id} has invalid authorization type: {type}` | Warning |\r\n| Unresolved environment variable | `unsubstituted macros: [var_name]` | Error |\r\n| Invalid JSON or HUJSON syntax | Parse error details | Error |\r\n| Invalid quota definition | `quota {name}: {details}` | Error |\r\n| **Structural / syntax** | | |\r\n| Duplicate keys in config | `duplicate config key \"hostname\"` | Warning |\r\n| Unknown config keys | `unknown config key \"basurl\"` | Warning |\r\n| Type mismatch in field value | Field name and `json.UnmarshalTypeError` details | Warning |\r\n| **Provider** | | |\r\n| Invalid `add_headers` format | `provider {id}: add_headers entry \"Bad-Entry\" must be in \"Header-Name: value\" format` | Warning |\r\n| **Quota** | | |\r\n| Invalid quota name template | `quota \"{name}\": quota name \"{name}\" has unsupported template \"{template}\" after colon` | Warning |\r\n| **Grant** | | |\r\n| Unknown fields in grant | Strict JSON parsing error for the unrecognized field | Warning |\r\n| Grant `models` references undefined provider | `models pattern \"{pattern}\" references provider \"{name}\" which does not match any declared provider` | Warning |\r\n| Grant `mcp_tools`, `mcp_resources`, or `mcp_templates` references undefined MCP server | `mcp_tools pattern \"{pattern}\" references server \"{name}\" which does not match any declared MCP server` | Warning |\r\n| Grant `send_hooks` references undefined hook | `send_hooks references undefined hook \"{name}\"` | Warning |\r\n| Grant `quotas` references undefined quota | `quotas references undefined quota \"{name}\"` | Warning |\r\n| Invalid quota bucket ref template in grant | `grants[{n}] grant {n} quotas[{n}]: bucket ref \"{ref}\" has unsupported template...` | Warning |\r\n| Grant-level `add_headers` invalid format | `add_headers entry \"{entry}\" must be in \"Header-Name: value\" format` | Warning |\r\n| **Hook** | | |\r\n| Hook missing URL | `hook {name} has no url configured` | Warning |\r\n| Hook invalid URL scheme | `hook {name} has invalid URL scheme (must be http:// or https://): {url}` | Warning |\r\n| Hook invalid authorization type | `hook {name} has invalid authorization type: {type}` | Warning |\r\n| **Exporter** | | |\r\n| S3 prefix ends with `/` | `exporters.s3.prefix must not end with a slash` | Warning |\r\n| **Structural warnings** | | |\r\n| No grants assign admin role | `no grant in grants or temp_grants assigns role:admin; nobody will be able to manage this instance unless admin is granted via tsnet ACL policy` | Warning |\r\n| Providers configured but no grants defined | `providers are configured but no grants or temp_grants defined; all access will be denied` | Warning |\r\n| **Save-only** | | |\r\n| Empty configuration | `config must not be empty` | Error |\r\n| Admin lockout prevention | Rejects saves that would remove the saving user's admin access | Error |\r\n\r\nAperture silently caps S3 exporter `limit_records` values above 2500 to 2500.\r\n\r\nFor common validation issues and how to resolve them, refer to [troubleshooting](https://tailscale.com/docs/aperture/troubleshooting).\r\n\r\n## [Complete example](https://tailscale.com/docs/aperture/configuration\\#complete-example)\r\n\r\nThe following example shows a complete configuration with all sections:\r\n\r\n```json\r\n{\r\n // Access control: who can use which models\r\n \"grants\": [\\\r\n // All users: access all models with per-user and org-wide quotas\\\r\n {\\\r\n \"src\": [\"*\"],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/aperture\": [\\\r\n { \"role\": \"user\" },\\\r\n {\\\r\n \"models\": \"**\",\\\r\n \"quotas\": [\\\r\n {\"bucket\": \"daily:\"},\\\r\n {\"bucket\": \"org-monthly\"},\\\r\n ],\\\r\n },\\\r\n ],\\\r\n },\\\r\n },\\\r\n // Admin access for specific user with audit hook\\\r\n {\\\r\n \"src\": [\"admin@company.com\"],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/aperture\": [\\\r\n { \"role\": \"admin\" },\\\r\n {\\\r\n \"models\": \"**\",\\\r\n \"send_hooks\": [\\\r\n {\\\r\n \"name\": \"oso\",\\\r\n \"events\": [\"tool_call_entire_request\"],\\\r\n \"send\": [\"tools\", \"estimated_cost\"],\\\r\n },\\\r\n ],\\\r\n },\\\r\n ],\\\r\n },\\\r\n },\\\r\n ],\r\n\r\n // Dollar-based spending limits\r\n \"quotas\": {\r\n \"daily:\": {\r\n \"capacity\": \"$10.00\",\r\n \"rate\": \"$5.00/day\",\r\n \"on_exceed\": \"reject\",\r\n },\r\n \"org-monthly\": {\r\n \"capacity\": \"$2000.00\",\r\n \"rate\": \"$2000.00/month\",\r\n \"on_exceed\": \"reject\",\r\n },\r\n },\r\n\r\n // LLM session log export configuration\r\n \"exporters\": {\r\n \"s3\": {\r\n // Required for S3-compatible services (GCS, MinIO, Backblaze B2, and others)\r\n \"endpoint\": \"https://your-s3-compatible-endpoint.url\",\r\n \"bucket_name\": \"aperture-exports\",\r\n \"region\": \"us-west-2\",\r\n \"prefix\": \"prod\",\r\n \"access_key_id\": \"YOUR_AWS_KEY\",\r\n \"access_secret\": \"YOUR_AWS_SECRET\",\r\n \"every\": 3600,\r\n \"limit\": 1000\r\n }\r\n },\r\n\r\n // LLM providers\r\n \"providers\": {\r\n \"openai\": {\r\n \"baseurl\": \"https://api.openai.com/\",\r\n \"apikey\": \"YOUR_OPENAI_KEY\",\r\n \"models\": [\"gpt-5\", \"gpt-5-mini\", \"gpt-4.1\"],\r\n \"name\": \"OpenAI\",\r\n \"description\": \"OpenAI models for coding and chat\",\r\n \"compatibility\": {\r\n \"openai_chat\": true,\r\n \"openai_responses\": true\r\n }\r\n },\r\n \"anthropic\": {\r\n \"baseurl\": \"https://api.anthropic.com\",\r\n \"apikey\": \"YOUR_PROXY_ANTHROPIC_KEY\",\r\n \"authorization\": \"x-api-key\",\r\n \"models\": [\"claude-sonnet-4-5\", \"claude-haiku-4-5\", \"claude-opus-4-5\"],\r\n \"name\": \"Anthropic\",\r\n \"compatibility\": {\r\n \"openai_chat\": false,\r\n \"anthropic_messages\": true\r\n }\r\n },\r\n \"gemini\": {\r\n \"baseurl\": \"https://generativelanguage.googleapis.com\",\r\n \"apikey\": \"YOUR_PROXY_GEMINI_KEY\",\r\n \"authorization\": \"x-goog-api-key\",\r\n \"models\": [\"gemini-2.5-flash\", \"gemini-2.5-pro\"],\r\n \"name\": \"Google Gemini\",\r\n \"compatibility\": {\r\n \"openai_chat\": false,\r\n \"gemini_generate_content\": true\r\n }\r\n },\r\n \"private\": {\r\n \"baseurl\": \"YOUR_PRIVATE_LLM_URL\",\r\n \"models\": [\"qwen3-coder-30b\"]\r\n }\r\n },\r\n\r\n // Hooks for external integrations\r\n \"hooks\": {\r\n \"oso\": {\r\n \"url\": \"https://api.osohq.com/api/agents/v1/model-request\",\r\n \"apikey\": \"YOUR_OSO_API_KEY\",\r\n },\r\n },\r\n\r\n // MCP server proxying\r\n \"mcp\": {\r\n \"accept_registrations\": true,\r\n \"servers\": {\r\n \"tools\": {\r\n \"url\": \"http://mcp-tools.example.ts.net:8080/v1/mcp\",\r\n },\r\n },\r\n },\r\n}\r\n```\r\n\r\n![Project Logo](https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed)\r\n\r\nAsk AI\r\n\r\nreCAPTCHA\r\n\r\nRecaptcha requires verification.\r\n\r\nprotected by **reCAPTCHA**\r\n","html":"

Aperture by Tailscale configuration

\n

Last validated: Apr 9, 2026

\n

Aperture by Tailscaleis currently in alpha.

\n

During the alpha testing period, Aperture by Tailscale is available at no additional cost across all Tailscale plans. Request access at aperture.tailscale.com. Aperture by Tailscale comes with six free users. Contact Tailscale for pricing if you need more than six users.

\n

Aperture by Tailscale uses a JSON configuration to specify LLM providers, access control policies, and optional integrations. The Aperture configuration controls which models are available, how requests authenticate with upstream providers, and who can access what. Admins can edit the configuration from the Settings page of the Aperture dashboard using the Visual editor (default) or the JSON editor.

\n

This page is part of the Aperture reference documentation.

\n

Minimal configuration

\n

A minimal configuration requires at least one provider with a base URL and at least one model. The following example shows a minimal configuration:

\n
{\r\n  \"providers\": {\r\n    \"anthropic\": {\r\n      \"baseurl\": \"https://api.anthropic.com\",\r\n      \"apikey\": \"YOUR_ANTHROPIC_API_KEY\",\r\n      \"models\": [\\\r\n        \"claude-sonnet-4-5\",\\\r\n        \"claude-opus-4-5\",\\\r\n      ],\r\n      \"authorization\": \"x-api-key\",\r\n      \"compatibility\": {\r\n        \"anthropic_messages\": true,\r\n      }\r\n    }\r\n  }\r\n}\n
\n

If you omit apikey, Aperture logs a warning at startup but continues to run. Most providers require an API key for authentication, so add one unless your provider handles authentication differently.

\n

The apikey field requires an API key from the provider's developer platform. Consumer and business subscription plans (such as Claude Pro or Claude Max, ChatGPT Plus, Pro, or Team, or Gemini Advanced) do not provide API keys and are not compatible with Aperture.

\n

Default configuration

\n

New Aperture instances use a default configuration that includes OpenAI and Anthropic providers with common models. The default grants all users access to all models. The following shows the default configuration:

\n
{\r\n    // The grants section uses the Tailscale ACL grant structure.\r\n    \"grants\": [\\\r\n        // Grant admin access (permission to see the settings and all other\\\r\n        // users in the dashboard).\\\r\n        {\\\r\n            \"src\": [\\\r\n                // Explicitly identify certain users by their Tailscale login.\\\r\n                \"example-user@example.com\",\\\r\n\\\r\n                // Grant admin access to everyone by default.\\\r\n                // Remove this after you've configured explicit admin\\\r\n                // access for yourself.\\\r\n                // BE CAREFUL! If you remove this without granting explicit\\\r\n                // admin access to yourself, you'll lose your ability\\\r\n                // to edit this file.\\\r\n                \"*\",\\\r\n            ],\\\r\n            \"app\": {\\\r\n                \"tailscale.com/cap/aperture\": [\\\r\n                    { \"role\": \"admin\" },\\\r\n                ],\\\r\n            },\\\r\n        },\\\r\n\\\r\n        // Every user who can access Aperture gets at least user-level access.\\\r\n        // Remove this and Aperture denies access entirely by default.\\\r\n        // Admin access in a separate grant takes precedence over this section.\\\r\n        {\\\r\n            \"src\": [\"*\"],\\\r\n            \"app\": {\\\r\n                \"tailscale.com/cap/aperture\": [\\\r\n                    { \"role\": \"user\" },\\\r\n                ],\\\r\n            },\\\r\n        },\\\r\n\\\r\n        // Default: allow all users to access all models from all providers.\\\r\n        // Without this grant, users can't access any models (deny by default).\\\r\n        {\\\r\n            \"src\": [\"*\"],\\\r\n            \"app\": {\\\r\n                \"tailscale.com/cap/aperture\": [\\\r\n                    { \"models\": \"**\" },\\\r\n                ],\\\r\n            },\\\r\n        },\\\r\n\\\r\n        // This example hook sends traffic to Oso if it matches certain\\\r\n        // parameters. Configure Oso in the \"hooks\" section for this to work.\\\r\n        {\\\r\n            \"src\": [\\\r\n                // No users by default. Try \"*\" to capture everyone's traffic.\\\r\n            ],\\\r\n            \"app\": {\\\r\n                \"tailscale.com/cap/aperture\": [\\\r\n                    {\\\r\n                        \"send_hooks\": [\\\r\n                            {\\\r\n                                \"name\": \"oso\",\\\r\n                                // Capturing only tool calls\\\r\n                                \"events\": [\"tool_call_entire_request\"],\\\r\n                                \"send\": [\"user_message\", \"tools\", \"request_body\", \"response_body\"],\\\r\n                            },\\\r\n                        ],\\\r\n                    },\\\r\n                ],\\\r\n            },\\\r\n        },\\\r\n    ],\r\n\r\n    // Configure your LLM backends here.\r\n    // Fill your API keys in below to share these providers with your team.\r\n    // There's no limit to the number of providers you can configure.\r\n    \"providers\": {\r\n        \"openai\": {\r\n            \"baseurl\": \"https://api.openai.com\",\r\n            \"name\": \"OpenAI\",\r\n            \"apikey\": \"YOUR_OPENAI_API_KEY\",\r\n            \"models\": [\\\r\n                \"gpt-5\",\\\r\n                \"gpt-5-mini\",\\\r\n                \"gpt-5-nano\",\\\r\n                \"gpt-4.1\",\\\r\n                \"gpt-4.1-nano\",\\\r\n                \"gpt-5.1-codex\",\\\r\n                \"gpt-5.1-codex-max\",\\\r\n            ],\r\n            \"compatibility\": {\r\n                \"openai_chat\": true,\r\n                \"openai_responses\": true,\r\n                \"anthropic_messages\": false,\r\n            },\r\n        },\r\n        \"anthropic\": {\r\n            \"baseurl\": \"https://api.anthropic.com\",\r\n            \"name\": \"Anthropic\",\r\n            \"apikey\": \"YOUR_ANTHROPIC_API_KEY\",\r\n            \"models\": [\\\r\n                \"claude-sonnet-4-5\",\\\r\n                \"claude-sonnet-4-5-20250929\",\\\r\n                \"claude-haiku-4-5\",\\\r\n                \"claude-haiku-4-5-20251001\",\\\r\n                \"claude-opus-4-5\",\\\r\n                \"claude-opus-4-5-20251101\",\\\r\n            ],\r\n            \"compatibility\": {\r\n                \"openai_chat\": false,\r\n                \"openai_responses\": false,\r\n                \"anthropic_messages\": true,\r\n            },\r\n        },\r\n    },\r\n\r\n    // Hooks are configured API endpoints that Aperture calls under certain\r\n    // conditions. The conditions themselves are configured in the\r\n    // \"grants\" section.\r\n    \"hooks\": {\r\n        \"oso\": {\r\n            \"url\":    \"https://api.osohq.com/api/agents/v1/model-request\",\r\n            \"apikey\": \"YOUR_OSO_API_KEY\",\r\n        },\r\n    },\r\n}\n
\n

Configuration reference

\n

The Aperture configuration contains several top-level sections that control different aspects of Aperture's behavior. The following table describes the available top-level sections:

\n

| Section | Required | Description |\r\n| --- | --- | --- |\r\n| providers | Yes | Map of LLM provider configurations. |\r\n| grants | No | Access control policies for users, models, and quotas. Uses the Tailscale grant structure. |\r\n| quotas | No | Dollar-based spending limits using token buckets. |\r\n| hooks | No | Webhook endpoint configurations. |\r\n| exporters | No | LLM session log export configuration. Currently supports S3-compatible storage. |\r\n| auto_cost_basis | No | Boolean (default true). When true, Aperture infers cost_basis from a provider's compatibility flags when no explicit cost_basis is set. Set to false to disable auto-inference, so only providers with an explicit cost_basis produce cost estimates. |

\n

providers

\n

The providers section specifies the LLM providers to which Aperture routes requests. A unique string key identifies each provider. The following example shows the basic structure:

\n
{\r\n  \"providers\": {\r\n    \"openai\": { ... },\r\n    \"anthropic\": { ... },\r\n    \"private\": { ... }\r\n  }\r\n}\n
\n

Each provider configuration accepts the following fields:

\n

| Field | Type | Required | Default | Description |\r\n| --- | --- | --- | --- | --- |\r\n| baseurl | string | Yes | N/A | Base URL for the provider's API. |\r\n| models | array | Yes | N/A | List of model IDs available from this provider. |\r\n| apikey | string | No | \"\" | API key for authentication. |\r\n| authorization | string | No | \"bearer\" | Authorization header type. |\r\n| name | string | No | \"\" | Display name for the UI. |\r\n| description | string | No | \"\" | Description shown in the UI. |\r\n| compatibility | object | No | openai_chat enabled, all others disabled | API compatibility flags. Refer to the provider compatibility reference for details. |\r\n| cost_basis | string | No | Auto-inferred | Override the pricing service used for cost estimation. Refer to the provider compatibility reference for valid values. |\r\n| preference | int | No | 0 | Routing priority when a model is available from multiple providers. Higher value wins. |\r\n| disabled | bool | No | false | Deactivates the provider without removing its configuration. Disabled providers are excluded from routing and /v1/models. |\r\n| add_headers | array | No | [] | Custom headers added to every upstream request for this provider. Each entry uses \"Header-Name: value\" format. |\r\n| model_cost_map | array | No | [] | Map unknown model names to known models for pricing. Refer to model cost map. |

\n

The authorization field is not required for all providers. For example, Vertex AI uses a service account key file instead of an API key (prefixed with keyfile::). Refer to set up a Vertex AI provider for step-by-step configuration instructions.

\n

Authorization types

\n

Different providers require different authorization header formats. The authorization field supports bearer (default, used by OpenAI and most providers), x-api-key (Anthropic), and x-goog-api-key (Google Gemini). For the full authorization types table and provider-specific details, refer to the provider compatibility reference.

\n

Provider compatibility

\n

The compatibility object specifies which API formats the provider supports. This determines which endpoints Aperture exposes for the provider's models. Flags include openai_chat (default enabled), openai_responses, anthropic_messages, gemini_generate_content, bedrock_model_invoke, and others. For the complete compatibility flags table, provider matrix, and configuration examples for each provider, refer to the provider compatibility reference.

\n

Provider examples

\n

For complete configuration examples for each supported provider (OpenAI, Anthropic, Google Gemini, Vertex AI, Amazon Bedrock, OpenRouter, and self-hosted LLMs), refer to the provider compatibility reference.

\n

Pricing and cost estimation

\n

Aperture estimates the dollar cost of every LLM request. Cost estimates power quotas, hook metadata, and the per-model pricing shown in the Aperture dashboard. Aperture auto-infers pricing for known providers based on compatibility flags, but you can override this with the cost_basis and model_cost_map provider fields. For the full list of cost_basis values, model cost mapping syntax, and per-provider pricing details, refer to the provider compatibility reference.

\n

Aperture surfaces cost data in several places:

\n
    \n
  • Models page of the Aperture dashboard: Each model shows per-million-token pricing (input/output) with a tooltip that includes cache, reasoning, image, and web search rates.
    • \n
  • CSV export: The Adoption page's Download CSV button exports usage data including token counts per model, user, and date.
    • \n
  • Hooks: Include \"estimated_cost\" in a hook's send array to receive dollar cost, cost basis, and token usage with every hook call. Refer to hook send types for details.
    • \n
\n

grants

\n

The grants section specifies access control policies that determine which users can access which models, what hooks fire, and which quotas apply. Grants use the Tailscale grant structure with capabilities scoped under \"tailscale.com/cap/aperture\". Aperture is deny-by-default: without a matching grant, a user cannot access any models.

\n

For step-by-step instructions on configuring access, refer to Control model access and Set up admin access.

\n

The grants section replaces the deprecated temp_grants syntax with a new structure. The temp_grants syntax still works but is not recommended for new configurations.

\n

You can specify grants in two places:

\n
    \n
  1. Aperture configuration: In the \"grants\" array (described below).
    2. \n
  2. Tailnet policy file: As app capabilities under \"tailscale.com/cap/aperture\", delivered to Aperture automatically through the Tailscale coordination server.
    3. \n
\n

Aperture merges grants from both sources additively. Roles escalate (user to admin) but never downgrade.

\n

Basic structure

\n

A grant specifies a source (src) and a set of app capabilities:

\n
\"grants\": [\\\r\n  {\\\r\n    \"src\": [\"*\"],               // who this grant applies to\\\r\n    \"app\": {\\\r\n      \"tailscale.com/cap/aperture\": [\\\r\n        // array of individual capabilities\\\r\n        { \"models\": \"**\" },     // allow access to all models\\\r\n      ],\\\r\n    },\\\r\n  },\\\r\n]\n
\n

Source match (src)

\n

The src field determines which users a grant applies to:

\n
    \n
  • \"*\": Matches everyone.
    • \n
  • \"alice@example.com\": Matches a specific Tailscale login name.
    • \n
  • \"(loopback)\": Matches local/loopback requests (useful for development).
    • \n
\n

Model access

\n

Each models field accepts a single glob pattern using fully-qualified provider/model format. To match multiple providers, use separate grant entries.

\n

| Pattern | Matches |\r\n| --- | --- |\r\n| \"**\" | All models from all providers |\r\n| \"anthropic/**\" | All Anthropic models |\r\n| \"openai/gpt-5\" | Exactly openai/gpt-5 |\r\n| \"*/claude-sonnet*\" | Any claude-sonnet* model from any single provider |\r\n| \"aperture-*/**\" | Any model from a provider whose name starts with aperture- |

\n

* matches a single path segment. ** matches zero or more segments.

\n

A grant with no models field is \"floating,\" meaning it applies globally (useful for hooks and quotas that apply regardless of model).

\n

Role assignment

\n

Roles determine a user's permission level:

\n
{ \"role\": \"admin\" }   // full admin access\r\n{ \"role\": \"user\" }    // standard user access\n
\n

Without a role grant, the user cannot access Aperture. If multiple grants match a given user, the highest-permissioned role (admin) wins.

\n

MCP access

\n

Aperture's MCP server support is experimental. The MCP grants syntax may change.

\n

Grant access to registered MCP items in the same way as models:

\n
{\r\n  \"mcp_tools\": \"local/*\",       // tools from the \"local\" MCP server\r\n  \"mcp_resources\": \"**\",        // all resources from all servers\r\n  \"mcp_templates\": \"remote/*\",  // templates from \"remote\" server\r\n}\n
\n

Additional capability fields

\n

Each capability object in the tailscale.com/cap/aperture array can also include these fields:

\n

| Field | Type | Description |\r\n| --- | --- | --- |\r\n| add_headers | array | Custom headers prepended to upstream requests when this grant matches. Each entry uses \"Header-Name: value\" format. |\r\n| enable_chat_ui | bool | Grants access to the chat UI feature. |\r\n| read_metrics | bool | Grants access to the /metrics Prometheus endpoint. |

\n

Custom app capabilities

\n

Grants can include capability keys beyond tailscale.com/cap/aperture. Aperture passes these through to hooks when you include the \"grants\" send type:

\n
{\r\n  \"src\": [\"admin@example.com\"],\r\n  \"app\": {\r\n    \"tailscale.com/cap/aperture\": [\\\r\n      { \"role\": \"admin\" },\\\r\n      { \"models\": \"**\" },\\\r\n    ],\r\n    // Custom capability — forwarded to hooks via \"grants\" send type\r\n    \"mycompany.com/cap/policy\": [\\\r\n      { \"tier\": \"enterprise\", \"department\": \"engineering\" },\\\r\n    ],\r\n  },\r\n},\n
\n

When a hook includes \"grants\" in its send array, these custom capabilities appear in the hook metadata. External systems can use these capabilities to make authorization decisions.

\n

Grants from the tailnet policy file

\n

Specify grants directly in the tailnet policy file to use Tailscale's groups, tags, and device postures. This is the recommended approach for organizations that already manage access through Tailscale:

\n
// In the tailnet policy file (not the Aperture config):\r\n\"grants\": [\\\r\n  {\\\r\n    \"src\": [\"group:engineering\"],\\\r\n    \"dst\": [\"tag:aperture\"],\\\r\n    \"app\": {\\\r\n      \"tailscale.com/cap/aperture\": [\\\r\n        { \"models\": \"**\" },\\\r\n        { \"role\": \"user\" },\\\r\n      ],\\\r\n    },\\\r\n  },\\\r\n  {\\\r\n    \"src\": [\"group:ml-team\"],\\\r\n    \"dst\": [\"tag:aperture\"],\\\r\n    \"app\": {\\\r\n      \"tailscale.com/cap/aperture\": [\\\r\n        { \"models\": \"**\" },\\\r\n        { \"role\": \"admin\" },\\\r\n      ],\\\r\n    },\\\r\n  },\\\r\n]\n
\n

Aperture receives these capabilities from the Tailscale peer information at request time and merges them with any grants specified in the Aperture configuration.

\n

You can also scope grants based on Tailscale device postures. For example, grant access to different models or quotas, or apply different hooks, based on whether a user is on a managed corporate laptop versus an unmanaged VM (virtual machine).

\n

Groups (for example, group:engineering) aren't available for grants specified in the Aperture configuration. The Tailscale coordination server tracks group membership information and does not share it with Aperture. Grants specified in the Aperture configuration can match on individual login names or tags.

\n

quotas

\n

The quotas section specifies dollar-based spending limits using token buckets. Each bucket has a capacity (maximum balance) and a refill rate. When a request's estimated cost would bring a bucket below zero, Aperture rejects the request with HTTP 429.

\n

For step-by-step instructions, refer to Set per-user spending limits and Set a team-wide budget. To check and refill budgets, refer to Check and refill budgets.

\n
\"quotas\": {\r\n  // Per-user daily budget: refills $5/day, can burst up to $10\r\n  \"daily:<user>\": {\r\n    \"capacity\": \"$10.00\",\r\n    \"rate\": \"$5.00/day\",\r\n    \"on_exceed\": \"reject\",\r\n  },\r\n\r\n  // Shared pool across all users who reference it\r\n  \"eng-team-pool\": {\r\n    \"capacity\": \"$100.00\",\r\n    \"rate\": \"$100.00/day\",\r\n    \"on_exceed\": \"reject\",\r\n  },\r\n\r\n  // Per-user limit for expensive models\r\n  \"opus:<user>\": {\r\n    \"capacity\": \"$5.00\",\r\n    \"rate\": \"$2.50/day\",\r\n    \"on_exceed\": \"reject\",\r\n  },\r\n}\n
\n

Each quota accepts the following fields:

\n

| Field | Format | Description |\r\n| --- | --- | --- |\r\n| capacity | \"$<amount>\" | Maximum balance the bucket can hold. Also the starting balance. |\r\n| rate | \"$<amount>/<unit>\" | How fast the bucket refills. Units: min, hour, day, week, month (30 days). |\r\n| on_exceed | \"reject\" | Action when the bucket is empty. The supported value is \"reject\" (HTTP 429). |

\n

Template variables

\n

Quota names can include template variables that expand at request time:

\n

| Template | Expands to | Example |\r\n| --- | --- | --- |\r\n| <user> | Caller's Tailscale login name or tag combination | daily:<user> expands to daily:alice@example.com |\r\n| <node> | Caller's node ID (a distinct quota for each node, even if nodes share the same user or tag) | device:<node> expands to device:nXXXXXXXXXCNTRL |

\n

Quotas without a template variable (for example, eng-team-pool) create a single shared bucket.

\n

Attach quotas to grants

\n

Quotas take effect only when attached to grants. A quota specified in the quotas section does nothing until a grant references it. When a request matches a grant, all quotas listed in that grant are charged at the same time:

\n
\"grants\": [\\\r\n  {\\\r\n    \"src\": [\"*\"],\\\r\n    \"app\": {\\\r\n      \"tailscale.com/cap/aperture\": [\\\r\n        {\\\r\n          \"models\": \"**\",\\\r\n          \"quotas\": [\\\r\n            {\"bucket\": \"daily:<user>\"},\\\r\n            {\"bucket\": \"eng-team-pool\"},\\\r\n          ],\\\r\n        },\\\r\n      ],\\\r\n    },\\\r\n  },\\\r\n]\n
\n

How multiple quotas interact

\n

When a grant references multiple quota buckets, all buckets must have a positive balance for the request to proceed. If any single bucket is exhausted, Aperture rejects the request, even if other buckets have remaining balance.

\n

After the response completes, Aperture deducts the estimated cost from every referenced bucket at the same time.

\n

A request can match multiple grants, each with their own quotas. Aperture collects and enforces all matching quotas together.

\n

Quota examples

\n

The following examples show common quota configurations.

\n
Per-user quota
\n

Each user gets their own bucket with independent capacity and refill rate:

\n
\"quotas\": {\r\n  \"daily:<user>\": {\r\n    \"capacity\": \"$10.00\",\r\n    \"rate\": \"$5.00/day\",\r\n    \"on_exceed\": \"reject\",\r\n  },\r\n},\r\n\"grants\": [\\\r\n  {\\\r\n    \"src\": [\"*\"],\\\r\n    \"app\": {\\\r\n      \"tailscale.com/cap/aperture\": [\\\r\n        { \"role\": \"user\" },\\\r\n        { \"models\": \"**\",\\\r\n          \"quotas\": [{\"bucket\": \"daily:<user>\"}] },\\\r\n      ],\\\r\n    },\\\r\n  },\\\r\n]\n
\n

This creates a separate bucket for each user (for example, daily:alice@example.com, daily:bob@example.com), each with $10 capacity and a $5/day refill.

\n
Quota scoped to specific models
\n

Apply a quota only when the request targets specific models:

\n
\"quotas\": {\r\n  \"opus:<user>\": {\r\n    \"capacity\": \"$5.00\",\r\n    \"rate\": \"$2.50/day\",\r\n    \"on_exceed\": \"reject\",\r\n  },\r\n},\r\n\"grants\": [\\\r\n  {\\\r\n    \"src\": [\"*\"],\\\r\n    \"app\": {\\\r\n      \"tailscale.com/cap/aperture\": [\\\r\n        // General access — no quota\\\r\n        { \"models\": \"**\" },\\\r\n        // Additional quota for Opus models only\\\r\n        {\\\r\n          \"models\": \"*/claude-opus*\",\\\r\n          \"quotas\": [{\"bucket\": \"opus:<user>\"}],\\\r\n        },\\\r\n      ],\\\r\n    },\\\r\n  },\\\r\n]\n
\n

The opus:<user> quota applies only when the request targets an Opus model. Other models are unmetered.

\n
Combine per-user and shared quotas
\n

Charge each request against both a personal budget and a shared team pool:

\n
\"quotas\": {\r\n  \"daily:<user>\": {\r\n    \"capacity\": \"$10.00\",\r\n    \"rate\": \"$5.00/day\",\r\n    \"on_exceed\": \"reject\",\r\n  },\r\n  \"team-pool\": {\r\n    \"capacity\": \"$200.00\",\r\n    \"rate\": \"$200.00/day\",\r\n    \"on_exceed\": \"reject\",\r\n  },\r\n},\r\n\"grants\": [\\\r\n  {\\\r\n    \"src\": [\"*\"],\\\r\n    \"app\": {\\\r\n      \"tailscale.com/cap/aperture\": [\\\r\n        { \"role\": \"user\" },\\\r\n        {\\\r\n          \"models\": \"**\",\\\r\n          \"quotas\": [\\\r\n            {\"bucket\": \"daily:<user>\"},\\\r\n            {\"bucket\": \"team-pool\"},\\\r\n          ],\\\r\n        },\\\r\n      ],\\\r\n    },\\\r\n  },\\\r\n]\n
\n

Every request deducts from both the user's personal bucket and the shared team pool. Aperture blocks a user who exhausts their $10 daily limit even if the team pool has remaining budget.

\n

hooks

\n

The hooks section specifies webhook endpoints that Aperture calls when conditions match. A unique string key identifies each hook, and grants reference this key. For step-by-step setup, refer to Build a custom webhook. For integration-specific guides, refer to Integrate Oso with Aperture or Integrate Cerbos with Aperture.

\n

The following example shows the hooks configuration:

\n
{\r\n  \"hooks\": {\r\n    \"oso\": {\r\n      \"url\": \"https://api.osohq.com/api/agents/v1/model-request\",\r\n      \"apikey\": \"YOUR_OSO_API_KEY\",\r\n      \"timeout\": \"10s\"\r\n    },\r\n    \"my-webhook\": {\r\n      \"url\": \"https://example.com/webhook\",\r\n      \"apikey\": \"YOUR_API_KEY\"\r\n    }\r\n  }\r\n}\n
\n

Each hook configuration accepts the following fields:

\n

| Field | Type | Required | Default | Description |\r\n| --- | --- | --- | --- | --- |\r\n| url | string | Yes | N/A | HTTP or HTTPS endpoint to POST hook data to. |\r\n| apikey | string | No | \"\" | API key that Aperture sends to the hook endpoint using the method specified by authorization. |\r\n| authorization | string | No | \"bearer\" | How Aperture sends the API key. Supports the same values as provider authorization: bearer, x-api-key, x-goog-api-key. |\r\n| timeout | string | No | \"5s\" | Maximum duration to wait for the hook to respond. |\r\n| disabled | boolean | No | false | Skips this hook when Aperture would otherwise call it. Useful for temporarily disabling a hook without removing its configuration. |

\n

The timeout field accepts Go duration strings such as 5s, 30s, or 1m. Set to 0 to disable the timeout.

\n

The send_hooks entries in the grants section trigger hooks. A hook specified here does nothing until a grant references it.

\n

Hook grants

\n

To trigger a hook, add a send_hooks entry to a capability in the grants section. Hook grants specify which requests trigger the hook and what data to send.

\n
{\r\n  \"grants\": [\\\r\n    {\\\r\n      \"src\": [\"*\"],\\\r\n      \"app\": {\\\r\n        \"tailscale.com/cap/aperture\": [\\\r\n          {\\\r\n            \"models\": \"**\",\\\r\n            \"send_hooks\": [\\\r\n              {\\\r\n                \"name\": \"oso\",\\\r\n                \"events\": [\"tool_call_entire_request\"],\\\r\n                \"send\": [\"tools\", \"user_message\", \"request_body\", \"response_body\"],\\\r\n              },\\\r\n            ],\\\r\n          },\\\r\n        ],\\\r\n      },\\\r\n    },\\\r\n  ]\r\n}\n
\n

Each send_hooks entry contains the following fields:

\n

| Field | Type | Description |\r\n| --- | --- | --- |\r\n| name | string | Key referencing a hook specified in the top-level hooks section. |\r\n| events | array | Event types that trigger the hook. |\r\n| send | array | List of data types to include in the hook payload. |

\n

Hook events

\n

| Event | Description |\r\n| --- | --- |\r\n| tool_call_entire_request | Fires once after the response completes if any message in the response contained tool calls. |\r\n| entire_request | Fires for every completed request. |

\n

Hook send types

\n

The send array specifies which data to include in the POST payload sent to the hook endpoint:

\n

| Field | Description |\r\n| --- | --- |\r\n| tools | Array of tool calls extracted from the response. |\r\n| request_body | The original request body sent to the LLM. |\r\n| user_message | The user's message from the request. |\r\n| response_body | The reconstructed response body JSON. |\r\n| raw_responses | Array of raw SSE messages (for streaming) or single response object. |\r\n| estimated_cost | Dollar cost estimate, pricing basis, and token usage breakdown. |\r\n| grants | Non-Aperture app capabilities from the user's grants (custom capabilities). |\r\n| quotas | Current state of all quota buckets that applied to this request. |

\n

estimated_cost

\n

Includes the dollar cost estimate, the pricing basis used, and a token usage breakdown. These fields appear inside the metadata object of the hook payload:

\n
{\r\n  \"models\": \"**\",\r\n  \"send_hooks\": [\\\r\n    {\\\r\n      \"name\": \"audit\",\\\r\n      \"events\": [\"tool_call_entire_request\"],\\\r\n      \"send\": [\"tools\", \"estimated_cost\"],\\\r\n    },\\\r\n  ],\r\n}\n
\n

The hook receives the cost data inside metadata:

\n
{\r\n  \"metadata\": {\r\n    \"login_name\": \"user@example.com\",\r\n    \"...\": \"...\",\r\n    \"estimated_cost\": {\r\n      \"dollars\": 0.0342,\r\n      \"cost_basis\": \"anthropic/claude-sonnet-4-5\",\r\n      \"usage\": {\r\n        \"input_tokens\": 1500,\r\n        \"output_tokens\": 800,\r\n        \"cached_tokens\": 200,\r\n        \"reasoning_tokens\": 0\r\n      }\r\n    }\r\n  },\r\n  \"tool_calls\": [...]\r\n}\n
\n

grants

\n

Includes any non-Aperture app capabilities from the user's grants. This lets external systems (policy engines, audit logs) access custom capabilities attached to the user. The grants data appears inside the metadata object:

\n
{\r\n  \"src\": [\"alice@example.com\"],\r\n  \"app\": {\r\n    \"tailscale.com/cap/aperture\": [\\\r\n      { \"models\": \"**\" },\\\r\n      {\\\r\n        \"send_hooks\": [\\\r\n          {\\\r\n            \"name\": \"policy-engine\",\\\r\n            \"events\": [\"entire_request\"],\\\r\n            \"send\": [\"estimated_cost\", \"grants\"],\\\r\n          },\\\r\n        ],\\\r\n      },\\\r\n    ],\r\n    \"mycompany.com/cap/policy\": [\\\r\n      {\"tier\": \"enterprise\", \"max_context\": 200000},\\\r\n    ],\r\n  },\r\n}\n
\n

The hook receives the custom capabilities inside metadata:

\n
{\r\n  \"metadata\": {\r\n    \"login_name\": \"alice@example.com\",\r\n    \"...\": \"...\",\r\n    \"grants\": {\r\n      \"mycompany.com/cap/policy\": [\\\r\n        {\"tier\": \"enterprise\", \"max_context\": 200000}\\\r\n      ]\r\n    },\r\n    \"estimated_cost\": { \"...\" }\r\n  }\r\n}\n
\n

quotas

\n

Includes the current state of all quota buckets that applied to the request. The quotas data appears inside the metadata object:

\n
\"send\": [\"tools\", \"quotas\"]\n
\n

The hook receives the bucket state inside metadata:

\n
{\r\n  \"metadata\": {\r\n    \"login_name\": \"alice@example.com\",\r\n    \"...\": \"...\",\r\n    \"quotas\": {\r\n      \"daily:alice@example.com\": {\r\n        \"current\": 7250000000,\r\n        \"capacity\": 10000000000,\r\n        \"rate\": \"$5.00/day\"\r\n      }\r\n    }\r\n  }\r\n}\n
\n

Values for current and capacity are in nanodollars (1 dollar = 1,000,000,000 nanodollars).

\n

Every hook call automatically includes a metadata object with request context:

\n
{\r\n  \"metadata\": {\r\n    \"login_name\": \"user@example.com\",\r\n    \"user_agent\": \"curl/8.0\",\r\n    \"url\": \"/v1/chat/completions\",\r\n    \"model\": \"gpt-5\",\r\n    \"provider\": \"openai\",\r\n    \"tailnet_name\": \"example.com\",\r\n    \"stable_node_id\": \"n12345\",\r\n    \"request_id\": \"abc123\",\r\n    \"session_id\": \"oacc_1a2b3c4d5e6f7890\"\r\n  }\r\n}\n
\n

Hook grant example

\n

The following example sends tool call data and cost estimates to an audit service for all requests from a specific user:

\n
{\r\n  \"grants\": [\\\r\n    {\\\r\n      \"src\": [\"developer@company.com\"],\\\r\n      \"app\": {\\\r\n        \"tailscale.com/cap/aperture\": [\\\r\n          {\\\r\n            \"models\": \"anthropic/**\",\\\r\n            \"send_hooks\": [\\\r\n              {\\\r\n                \"name\": \"my-webhook\",\\\r\n                \"events\": [\"tool_call_entire_request\"],\\\r\n                \"send\": [\"tools\", \"user_message\", \"estimated_cost\"],\\\r\n              },\\\r\n            ],\\\r\n          },\\\r\n          {\\\r\n            \"models\": \"openai/**\",\\\r\n            \"send_hooks\": [\\\r\n              {\\\r\n                \"name\": \"my-webhook\",\\\r\n                \"events\": [\"tool_call_entire_request\"],\\\r\n                \"send\": [\"tools\", \"user_message\", \"estimated_cost\"],\\\r\n              },\\\r\n            ],\\\r\n          },\\\r\n        ],\\\r\n      },\\\r\n    },\\\r\n  ]\r\n}\n
\n

exporters

\n

The exporters section configures periodic export of LLM session logs to external storage. Currently, Aperture supports exporting to S3-compatible storage (AWS S3, Google Cloud Storage, MinIO, Backblaze B2, and others). For step-by-step setup, refer to Export usage data to S3.

\n

The following example shows the exporters configuration:

\n
{\r\n  \"exporters\": {\r\n    \"s3\": {\r\n      \"endpoint\": \"https://your-s3-compatible-endpoint.url\",\r\n      \"bucket_name\": \"aperture-exports\",\r\n      \"region\": \"us-east-1\",\r\n      \"prefix\": \"prod\",\r\n      \"access_key_id\": \"YOUR_AWS_KEY\",\r\n      \"access_secret\": \"YOUR_AWS_SECRET\",\r\n      \"every\": 3600,\r\n      \"limit\": 1000\r\n    }\r\n  }\r\n}\n
\n

Setting bucket_name to a non-empty value enables the S3 exporter. Each S3 exporter configuration accepts the following fields:

\n

| Field | Type | Required | Default | Description |\r\n| --- | --- | --- | --- | --- |\r\n| endpoint | string | No | \"\" | HTTP endpoint for an S3-compatible API. Required for non-AWS services (GCS, MinIO, Backblaze B2). Omit for Amazon S3, where Aperture infers the endpoint from region. |\r\n| bucket_name | string | Conditional | null | Name of the S3 bucket to upload exports to. Setting this field to a non-empty value enables the S3 exporter. |\r\n| region | string | No | \"us-east-1\" | AWS region for the bucket. Required even for non-AWS endpoints because the AWS SDK validates this field. |\r\n| prefix | string | No | \"\" | Path prefix for new S3 objects. Must not end with /. |\r\n| access_key_id | string | Conditional | null | AWS access key ID used to authenticate. Required and must be non-empty when bucket_name is set and static credentials are used. |\r\n| access_secret | string | Conditional | null | Secret key used with access_key_id to authenticate. Required and must be non-empty when access_key_id is set. |\r\n| every | int | No | 3600 | Number of seconds to wait after the last export before starting another. Default is one hour. |\r\n| limit | int | No | 1000 | Maximum number of records per export. Aperture caps this value at 2500 and silently reduces higher values. |

\n

MCP

\n

Aperture's MCP server support is experimental. The MCP configuration syntax may change.

\n

The mcp section configures MCP (Model Context Protocol) server proxying. Aperture connects to remote MCP servers, aggregates their tools, resources, and resource templates, and exposes them through a single /v1/mcp endpoint. Refer to MCP server proxying for setup instructions and troubleshooting.

\n
{\r\n  \"mcp\": {\r\n    \"accept_registrations\": true,\r\n    \"servers\": {\r\n      \"local\": {\r\n        \"url\": \"http://localhost:8185/v1/mcp\"\r\n      },\r\n      \"remote\": {\r\n        \"url\": \"http://mcp-server.example.ts.net:8080/v1/mcp\"\r\n      }\r\n    }\r\n  }\r\n}\n
\n

mcp fields

\n

| Field | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| accept_registrations | boolean | false | Allow backends to register dynamically through POST /v1/mcp/register. Backends POST {\"url\": \"http://...\"} and keep the connection open. Tools are unregistered when the connection closes. |\r\n| servers | map | {} | Map of server ID to server configuration. The map key is the server ID, which becomes the name prefix for tools (serverID_toolname), resources (serverID-uri), and resource templates (serverID-uriTemplate) from that backend. |

\n

servers fields

\n

Each entry in the servers map accepts the following fields:

\n

| Field | Type | Required | Description |\r\n| --- | --- | --- | --- |\r\n| url | string | Yes | The MCP server endpoint URL (for example, http://localhost:8185/v1/mcp). |

\n

Quota enforcement

\n

Aperture enforces quotas at request time by checking all referenced buckets before forwarding a request to the provider.

\n

What happens when a request exceeds a quota

\n

When a request would exceed any of its quota buckets, Aperture:

\n
    \n
  1. Rejects the request with HTTP status 429 (Too Many Requests).
    2. \n
  2. Sets a Retry-After header with the estimated seconds until enough budget refills.
    3. \n
  3. Formats the error to match the provider's native error format.
    4. \n
  4. Logs a warning with the bucket detail, login name, and model.
    5. \n
\n

The following table describes the provider-specific error formats:

\n

| Provider | Error format |\r\n| --- | --- |\r\n| Anthropic | {\"type\":\"error\",\"error\":{\"type\":\"rate_limit_error\",\"message\":\"...\"}} |\r\n| OpenAI | {\"error\":{\"message\":\"...\",\"type\":\"insufficient_quota\",\"code\":\"insufficient_quota\"}} |\r\n| Bedrock | {\"message\":\"...\"} with x-amzn-ErrorType: ThrottlingException |\r\n| Google/Vertex | {\"error\":{\"code\":429,\"message\":\"...\",\"status\":\"RESOURCE_EXHAUSTED\"}} |

\n

Where Aperture logs enforcement

\n

Aperture logs quota exceeded events at the Warn level in the server log with the following fields:

\n
    \n
  • detail: Which buckets Aperture exhausted.
    • \n
  • login_name: The user that Aperture blocked.
    • \n
  • model: The provider/model that the user requested.
    • \n
\n

Validation

\n

Aperture validates configuration at load time and reports problems. Some issues are fatal errors that prevent the configuration from loading, while others are warnings that let the configuration load but should be addressed. The following table describes the validations.

\n

Aperture handles validation differently depending on how the configuration is loaded:

\n
    \n
  • When Aperture loads configuration at startup or reload: Aperture logs warnings but loads the configuration successfully. This lets Aperture start even with minor issues.
    • \n
  • When saving through the API or the Settings page of the Aperture dashboard: Aperture treats warnings as errors and rejects the save. This ensures that configurations saved through the UI are warning-free.
    • \n
  • When using the validate endpoint (POST /aperture/config:validate): Aperture surfaces warnings as validation errors (the response sets Valid: false), matching the save behavior.
    • \n
\n

The admin lockout check only applies when saving — it prevents you from accidentally removing your own admin access.

\n

| Condition | Message | Severity |\r\n| --- | --- | --- |\r\n| No providers or MCP servers | no providers or mcp servers defined; users will not be able to access any models | Warning |\r\n| Provider missing baseurl | provider {id} has no baseurl configured | Warning |\r\n| Invalid authorization type | provider {id} has invalid authorization type: {type} | Warning |\r\n| Unresolved environment variable | unsubstituted macros: [var_name] | Error |\r\n| Invalid JSON or HUJSON syntax | Parse error details | Error |\r\n| Invalid quota definition | quota {name}: {details} | Error |\r\n| Structural / syntax | | |\r\n| Duplicate keys in config | duplicate config key \"hostname\" | Warning |\r\n| Unknown config keys | unknown config key \"basurl\" | Warning |\r\n| Type mismatch in field value | Field name and json.UnmarshalTypeError details | Warning |\r\n| Provider | | |\r\n| Invalid add_headers format | provider {id}: add_headers entry \"Bad-Entry\" must be in \"Header-Name: value\" format | Warning |\r\n| Quota | | |\r\n| Invalid quota name template | quota \"{name}\": quota name \"{name}\" has unsupported template \"{template}\" after colon | Warning |\r\n| Grant | | |\r\n| Unknown fields in grant | Strict JSON parsing error for the unrecognized field | Warning |\r\n| Grant models references undefined provider | models pattern \"{pattern}\" references provider \"{name}\" which does not match any declared provider | Warning |\r\n| Grant mcp_tools, mcp_resources, or mcp_templates references undefined MCP server | mcp_tools pattern \"{pattern}\" references server \"{name}\" which does not match any declared MCP server | Warning |\r\n| Grant send_hooks references undefined hook | send_hooks references undefined hook \"{name}\" | Warning |\r\n| Grant quotas references undefined quota | quotas references undefined quota \"{name}\" | Warning |\r\n| Invalid quota bucket ref template in grant | grants[{n}] grant {n} quotas[{n}]: bucket ref \"{ref}\" has unsupported template... | Warning |\r\n| Grant-level add_headers invalid format | add_headers entry \"{entry}\" must be in \"Header-Name: value\" format | Warning |\r\n| Hook | | |\r\n| Hook missing URL | hook {name} has no url configured | Warning |\r\n| Hook invalid URL scheme | hook {name} has invalid URL scheme (must be http:// or https://): {url} | Warning |\r\n| Hook invalid authorization type | hook {name} has invalid authorization type: {type} | Warning |\r\n| Exporter | | |\r\n| S3 prefix ends with / | exporters.s3.prefix must not end with a slash | Warning |\r\n| Structural warnings | | |\r\n| No grants assign admin role | no grant in grants or temp_grants assigns role:admin; nobody will be able to manage this instance unless admin is granted via tsnet ACL policy | Warning |\r\n| Providers configured but no grants defined | providers are configured but no grants or temp_grants defined; all access will be denied | Warning |\r\n| Save-only | | |\r\n| Empty configuration | config must not be empty | Error |\r\n| Admin lockout prevention | Rejects saves that would remove the saving user's admin access | Error |

\n

Aperture silently caps S3 exporter limit_records values above 2500 to 2500.

\n

For common validation issues and how to resolve them, refer to troubleshooting.

\n

Complete example

\n

The following example shows a complete configuration with all sections:

\n
{\r\n  // Access control: who can use which models\r\n  \"grants\": [\\\r\n    // All users: access all models with per-user and org-wide quotas\\\r\n    {\\\r\n      \"src\": [\"*\"],\\\r\n      \"app\": {\\\r\n        \"tailscale.com/cap/aperture\": [\\\r\n          { \"role\": \"user\" },\\\r\n          {\\\r\n            \"models\": \"**\",\\\r\n            \"quotas\": [\\\r\n              {\"bucket\": \"daily:<user>\"},\\\r\n              {\"bucket\": \"org-monthly\"},\\\r\n            ],\\\r\n          },\\\r\n        ],\\\r\n      },\\\r\n    },\\\r\n    // Admin access for specific user with audit hook\\\r\n    {\\\r\n      \"src\": [\"admin@company.com\"],\\\r\n      \"app\": {\\\r\n        \"tailscale.com/cap/aperture\": [\\\r\n          { \"role\": \"admin\" },\\\r\n          {\\\r\n            \"models\": \"**\",\\\r\n            \"send_hooks\": [\\\r\n              {\\\r\n                \"name\": \"oso\",\\\r\n                \"events\": [\"tool_call_entire_request\"],\\\r\n                \"send\": [\"tools\", \"estimated_cost\"],\\\r\n              },\\\r\n            ],\\\r\n          },\\\r\n        ],\\\r\n      },\\\r\n    },\\\r\n  ],\r\n\r\n  // Dollar-based spending limits\r\n  \"quotas\": {\r\n    \"daily:<user>\": {\r\n      \"capacity\": \"$10.00\",\r\n      \"rate\": \"$5.00/day\",\r\n      \"on_exceed\": \"reject\",\r\n    },\r\n    \"org-monthly\": {\r\n      \"capacity\": \"$2000.00\",\r\n      \"rate\": \"$2000.00/month\",\r\n      \"on_exceed\": \"reject\",\r\n    },\r\n  },\r\n\r\n  // LLM session log export configuration\r\n  \"exporters\": {\r\n    \"s3\": {\r\n      // Required for S3-compatible services (GCS, MinIO, Backblaze B2, and others)\r\n      \"endpoint\": \"https://your-s3-compatible-endpoint.url\",\r\n      \"bucket_name\": \"aperture-exports\",\r\n      \"region\": \"us-west-2\",\r\n      \"prefix\": \"prod\",\r\n      \"access_key_id\": \"YOUR_AWS_KEY\",\r\n      \"access_secret\": \"YOUR_AWS_SECRET\",\r\n      \"every\": 3600,\r\n      \"limit\": 1000\r\n    }\r\n  },\r\n\r\n  // LLM providers\r\n  \"providers\": {\r\n    \"openai\": {\r\n      \"baseurl\": \"https://api.openai.com/\",\r\n      \"apikey\": \"YOUR_OPENAI_KEY\",\r\n      \"models\": [\"gpt-5\", \"gpt-5-mini\", \"gpt-4.1\"],\r\n      \"name\": \"OpenAI\",\r\n      \"description\": \"OpenAI models for coding and chat\",\r\n      \"compatibility\": {\r\n        \"openai_chat\": true,\r\n        \"openai_responses\": true\r\n      }\r\n    },\r\n    \"anthropic\": {\r\n      \"baseurl\": \"https://api.anthropic.com\",\r\n      \"apikey\": \"YOUR_PROXY_ANTHROPIC_KEY\",\r\n      \"authorization\": \"x-api-key\",\r\n      \"models\": [\"claude-sonnet-4-5\", \"claude-haiku-4-5\", \"claude-opus-4-5\"],\r\n      \"name\": \"Anthropic\",\r\n      \"compatibility\": {\r\n        \"openai_chat\": false,\r\n        \"anthropic_messages\": true\r\n      }\r\n    },\r\n    \"gemini\": {\r\n      \"baseurl\": \"https://generativelanguage.googleapis.com\",\r\n      \"apikey\": \"YOUR_PROXY_GEMINI_KEY\",\r\n      \"authorization\": \"x-goog-api-key\",\r\n      \"models\": [\"gemini-2.5-flash\", \"gemini-2.5-pro\"],\r\n      \"name\": \"Google Gemini\",\r\n      \"compatibility\": {\r\n        \"openai_chat\": false,\r\n        \"gemini_generate_content\": true\r\n      }\r\n    },\r\n    \"private\": {\r\n      \"baseurl\": \"YOUR_PRIVATE_LLM_URL\",\r\n      \"models\": [\"qwen3-coder-30b\"]\r\n    }\r\n  },\r\n\r\n  // Hooks for external integrations\r\n  \"hooks\": {\r\n    \"oso\": {\r\n      \"url\": \"https://api.osohq.com/api/agents/v1/model-request\",\r\n      \"apikey\": \"YOUR_OSO_API_KEY\",\r\n    },\r\n  },\r\n\r\n  // MCP server proxying\r\n  \"mcp\": {\r\n    \"accept_registrations\": true,\r\n    \"servers\": {\r\n      \"tools\": {\r\n        \"url\": \"http://mcp-tools.example.ts.net:8080/v1/mcp\",\r\n      },\r\n    },\r\n  },\r\n}\n
\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}