Route Pi LLM providers through Tailscale Aperture

Route Pi LLM providers and connector tools through Tailscale Aperture, a managed AI gateway on your tailnet.
Aperture handles API key injection and request routing server-side. This extension integrates Pi with Aperture through three independent capabilities:
aperture provider whose models come from the gateway.Each capability is independent. Enable dedicated, proxy, connectors, or any combination.
pi install npm:@aliou/pi-ts-aperture
After installing, run the onboarding wizard:
/aperture:onboarding
The wizard walks you through:
/v1/models health check (e.g. ai.your-tailnet.ts.net).You can change everything later with:
/aperture:settings
Registers a standalone aperture provider whose model list comes from the Aperture gateway. You can include all gateway providers or filter to specific gateway providers during onboarding or in settings.
Dedicated model IDs are the model IDs reported by Aperture. They are not prefixed with the upstream provider ID. The extension keeps an internal route map so each model uses the Pi API that matches its Aperture provider compatibility.
Because Aperture does not expose every Pi model capability yet, models use safe defaults on first load: 128k context, 8k max output, text input, and no reasoning. Gateway pricing is mapped to Pi costs when Aperture returns pricing data.
In dedicated mode, the onboarding extension can stay enabled until model metadata is synced and validated. It exposes:
sync-aperture-models skill: looks up real capabilities such as context window, max tokens, reasoning, and input modalities, then updates ~/.pi/agent/models.json.aperture_validate_models_json tool: validates Pi’s models.json schema and checks that Aperture models include capability fields.aperture_complete_onboarding tool: marks onboarding complete and disables the temporary onboarding tools and skill after validation passes.User-defined model entries in models.json take precedence over gateway defaults and persist across restarts. The extension still owns routing details and cost data from Aperture gateway pricing.
Reroutes existing Pi providers (anthropic, openai, openai-codex, etc.) through Aperture. Each provider keeps its own model definitions and settings. Only the base URL, API key, and headers are overridden.
Proxy provider selection maps Aperture providers to local Pi registry providers by base URL. It supports child path matching, so an Aperture provider under https://chatgpt.com/backend-api/codex can match Pi’s local https://chatgpt.com/backend-api provider. If base URLs are unavailable, matching also falls back to provider IDs.
Proxy mode is useful when you want Pi’s native per-provider model configuration but want requests to go through Aperture for server-side credentials and routing.
Aperture can expose MCP connectors (GitHub, your own internal tools, …) at /v1/mcp. When connectors.enabled is on, this extension discovers gateway tools and registers them with Pi in one of two ways:
aperture_connector_listaperture_connector_tool_searchaperture_connector_tool_describeaperture_connector_tool_callconnectors.pinnedTools) that register as first-class Pi tools, surfaced directly to the model. Pin a small set you use every session; each pin adds its full schema to the system prompt.Enable connectors in /aperture:settings. Saved pin changes take effect on the next Pi restart (Pi cannot unregister tools at runtime).
| Command | Description |
|---|---|
/aperture:onboarding | Onboarding wizard. Only available while onboarding is enabled. |
/aperture:settings | Settings UI to update connection, capabilities, proxy providers, dedicated provider filters, pinned connector tools, onboarding status, and the onboarding extension toggle. |
The extension reads providers from GET /api/providers and cross-references
GET /v1/models. Disabled providers’ models do not appear in /v1/models,
so any provider whose models are all absent from it is dropped (and each
provider’s model list is intersected with /v1/models), leaving only
providers that are enabled and callable for the current grant.
Requests sent through Aperture include provenance headers:
Referer: https://pi.devX-Title: npm:@aliou/pi-ts-aperturex-session-id for grouping requests in the Aperture dashboardFor each configured upstream provider, the extension calls registerProvider with:
baseUrl set to your Aperture URL + /v1 for most Pi APIs.baseUrl set to the Aperture root for APIs where Pi appends its own path, such as anthropic-messages and openai-codex-responses.apiKey set to "-" because Aperture injects upstream credentials server-side. OAuth credentials still take precedence when Pi has them.Optional gateway model verification can warn when configured Pi models are missing from the Aperture gateway.
Dedicated mode fetches models from Aperture, maps provider compatibility to Pi APIs, merges gateway defaults with user-defined providers.aperture.models from ~/.pi/agent/models.json, and registers an aperture provider.
Compatibility controls the Pi API and base URL used for each upstream provider at runtime. For example, OpenAI-compatible providers use /v1, Anthropic-compatible providers use the gateway root, Gemini-compatible providers use /v1beta, and Vertex-compatible providers use /v1.
User-defined models from models.json take precedence over gateway defaults, so custom capabilities such as reasoning, context window, max output, and input modalities are preserved across restarts. If a user model does not define cost, the extension keeps the cost derived from Aperture gateway pricing.
Configuration is saved globally to ~/.pi/agent/extensions/aperture.json.
{
"baseUrl": "http://ai.your-tailnet.ts.net",
"onboardingDone": true,
"onboarding": {
"enabled": false
},
"proxy": {
"enabled": true,
"upstreamProviders": [
{ "id": "anthropic", "shouldCheckGatewayModels": true }
]
},
"dedicated": {
"enabled": true,
"providers": [
{ "id": "anthropic", "name": "Anthropic", "enabled": true },
{ "id": "openai", "name": "OpenAI", "enabled": true },
{ "id": "google", "name": "Google", "enabled": false }
]
},
"connectors": {
"enabled": false,
"discoveryTools": true,
"pinnedTools": [
{ "connectorId": "github", "toolName": "github_list_repos" }
]
}
}
Notes:
mode setting. Use proxy.enabled, dedicated.enabled, and connectors.enabled independently.dedicated.providers list means all Aperture gateway providers are included.~/.pi/agent/models.json, not in the extension config.github_list_repos); connectorId is stored for traceability. Pinned tools that no longer exist on the gateway are silently skipped.http:// or https://).