Aliou Diallo
projects releases npm github

pi-ts-aperture

Route Pi LLM providers through Tailscale Aperture

banner

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:

Each capability is independent. Enable dedicated, proxy, connectors, or any combination.

Install

pi install npm:@aliou/pi-ts-aperture

First run

After installing, run the onboarding wizard:

/aperture:onboarding

Onboarding walkthrough

The wizard walks you through:

  1. Aperture base URL, with a /v1/models health check (e.g. ai.your-tailnet.ts.net).
  2. Capability selection: dedicated, proxy, or both.
  3. Provider selection:
    • Dedicated: choose which Aperture gateway providers to include.
    • Proxy: choose matching local Pi providers to route through Aperture, with optional gateway model verification.
  4. Recap, save, and reload Pi so the selected capabilities are registered cleanly.

You can change everything later with:

/aperture:settings

Capabilities

Dedicated provider (default)

Dedicated provider walkthrough

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.

Sync model capabilities

In dedicated mode, the onboarding extension can stay enabled until model metadata is synced and validated. It exposes:

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.

Proxy existing providers

Proxy providers walkthrough

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.

Connectors

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:

Connectors walkthrough

Enable connectors in /aperture:settings. Saved pin changes take effect on the next Pi restart (Pi cannot unregister tools at runtime).

Commands

CommandDescription
/aperture:onboardingOnboarding wizard. Only available while onboarding is enabled.
/aperture:settingsSettings UI to update connection, capabilities, proxy providers, dedicated provider filters, pinned connector tools, onboarding status, and the onboarding extension toggle.

How it works

Aperture API usage

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.

Request routing

Requests sent through Aperture include provenance headers:

Proxy routing

For each configured upstream provider, the extension calls registerProvider with:

Optional gateway model verification can warn when configured Pi models are missing from the Aperture gateway.

Dedicated routing

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

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:

Requirements