OpenCode Tailscale Aperture Plugin

Automatically populate models from Tailscale Aperture.

OpenCode compatibility

The same package supports OpenCode v1 (1.4.0 or newer) and the new v2 plugin API. The default export provides v1 server and v2 setup entry points; direct callers can still import the named TailscaleAperturePlugin function for v1. The v2 adapter targets the API shipped in @opencode/plugin 2.0.5.

Both entry points share model discovery, provider grouping, protocol selection, and Models.dev enrichment. V2 registers replayable provider transforms and maps limits, modalities, costs, release dates, and reasoning variants to its model schema. Existing catalog settings take precedence over discovery defaults. Effort variants use each protocol's wire format; they are not generated for Bedrock or custom SDKs, which have no common effort parameter.

The two model lookup tools remain v1-only and v2 diagnostics go to stderr. OpenCode v2 supplies project, session, and client headers to model requests. V2's model schema also has no equivalent for v1's reasoning, temperature, attachment, or interleaved flags; input modalities still describe supported attachments.

Configuration

Configure the Aperture base URL using one of these methods (in order of precedence):

1. Plugin Options (opencode.json)

OpenCode v1:

{
  "plugin": [
    ["opencode-plugin-tsaperture", { "baseUrl": "http://ai.my-tailnet.ts.net" }]
  ]
}

OpenCode v2:

{
  "plugins": [
    {
      "package": "opencode-plugin-tsaperture",
      "options": { "baseUrl": "http://ai.my-tailnet.ts.net" }
    }
  ]
}

2. Environment Variable

export APERTURE_BASE_URL="http://ai.my-tailnet.ts.net"

3. Config File (aperture.json)

Create aperture.json in the opencode config directory:

macOS:

~/Library/Application\ Support/opencode/aperture.json

Linux:

~/.config/opencode/aperture.json

Windows:

%APPDATA%\opencode\aperture.json

Contents:

{
  "baseUrl": "http://ai.my-tailnet.ts.net",
  "apiKey": ""
}

apiKey is optional. Set it when your Aperture endpoint requires bearer auth. If omitted, the plugin passes an empty key to the generated providers.

API compatibility

The plugin reads Aperture provider compatibility metadata and registers each provider with the matching OpenCode provider package and endpoint. It supports OpenAI Responses and Chat Completions, Anthropic Messages, Google Vertex, Amazon Bedrock, and Gemini Generate Content routes.

Models.dev enrichment

The plugin enriches Aperture's /v1/models response with the same Models.dev catalog OpenCode uses. When a discovered model matches a catalog provider/model ID, the generated OpenCode config includes the catalog's family, release date, cost, modalities, reasoning/tool/temperature support, interleaved reasoning field, variants, and accurate limit.context, limit.input, and limit.output values.

Important: For full provider-specific feature support, the Aperture provider id and model id should match the Models.dev respective IDs. Provider IDs with an -x- suffix use the base ID for Models.dev lookup, so opencode-go-x-anthropic and opencode-go-x-responses both use the opencode-go catalog entry while retaining their separate API compatibility and SDK configuration.

Optional aperture.json fields:

{
  "modelsDevUrl": "https://models.dev",
  "modelsDevPath": "/path/to/models-dev-api.json",
  "disableModelsDev": false
}

The plugin also honors OpenCode's OPENCODE_MODELS_URL, OPENCODE_MODELS_PATH, and OPENCODE_DISABLE_MODELS_FETCH environment variables.

Usage

Once configured, Aperture models appear in the model picker. On v1, the assistant can also call these plugin tools:

• list_aperture_models - List available models from Aperture
• get_aperture_model with modelId - Get model details