Get started with Aperture

Requirements

Before deploying Aperture, ensure your environment meets these requirements.

• One or more LLM provider accounts

  You need API keys for any LLM providers to route through Aperture. Aperture supports the following providers:

  • OpenAI (GPT-4o, o1, o3-mini, and other models)
  • Anthropic (Claude Sonnet, Claude Opus, and other models)
  • Google (Gemini models)
  • OpenRouter (provides access to open source models such as DeepSeek, Qwen, and others)
  • OpenAI-compatible APIs (for example, llama.cpp and other self-hosted endpoints)

  Aperture requires API keys from provider developer platforms. 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.

• A Tailscale account

  The Aperture server runs on a Tailscale network (tailnet). When you sign up for Aperture, the process creates a free Tailscale account for you if you don't already have one.

  Aperture uses Tailscale identity to authenticate users automatically. When a client connects, the proxy identifies the user by their login name and device. This enables API access without distributing keys to individual users because Aperture centrally manages provider credentials and injects them when forwarding requests.

• Client connectivity

  Clients can connect to Aperture in two ways:

  • From inside the tailnet (recommended): Clients on the same tailnet as Aperture get full per-user identity, zero-key authentication, and granular access controls. Install Tailscale on each client device to join the tailnet.
  • From outside the tailnet: Clients that are not in the tailnet can use the ts-unplug tool, which creates a lightweight tailnet device and proxies local traffic to the Aperture instance. Each ts-unplug instance authenticates as a single tailnet identity. If each person runs their own ts-unplug, they get individual user attribution. Refer to enable Aperture without a tailnet for setup instructions.

Sign up

Aperture by Tailscale is a managed service that Tailscale hosts and maintains. To create an Aperture instance, visit aperture.tailscale.com and complete the sign-up process. If you don't have a Tailscale account, the sign-up process creates a free one for you.

After you have access to Aperture, follow the remaining sections on this page to configure providers and test your setup, then proceed to grant user access and connect LLM clients.

Configure Aperture settings

To configure Aperture settings, go to the Aperture dashboard. The Aperture dashboard is available to devices in the same tailnet at http://ai/ui. If you connect through ts-unplug, access the interface at http://localhost:<PORT_NUMBER>/ui/.

1. Open the Settings page of the Aperture dashboard.
2. Update the Aperture configuration to include the LLM providers and models you plan to use.
3. Configure any additional settings.

The following example configures Aperture with access to Anthropic's Claude Sonnet 4.5 and Claude Opus 4.5 models.

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

If you don't customize the Aperture configuration, Aperture uses the default configuration. Refer to the Aperture configuration reference for details on all available settings.

Test your Aperture configuration

After configuring providers, test your connection using curl commands from a device connected to the tailnet. If you connect through ts-unplug, use http://localhost:<PORT_NUMBER> instead of http://ai.

Test Anthropic API format:

curl -s http://ai/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-4-5-20251001",
    "max_tokens": 25,
    "messages": [{"role": "user", "content": "respond with: hello"}]
  }'

Test OpenAI API format:

curl -s http://ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "respond with: hello"}]
  }'

Test OpenAI Responses API format:

curl -s http://ai/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": [{"role": "user", "content": "respond with: hello"}]
  }'

If the requests succeed, Aperture is correctly routing to your configured providers. Visit the Aperture dashboard at http://ai/ui/ to see the requests in your usage history.

Next steps

After configuring and testing Aperture:

1. Grant users access to models so they can send requests.
2. Set up your LLM clients to route traffic through Aperture.
3. (Optional) Set spending limits to control costs.

Enable Aperture without a tailnet

You can use Aperture from a device that is not on the same tailnet as the Aperture deployment using the ts-plug and ts-unplug tools.

Each ts-unplug instance authenticates as a single tailnet identity. If each person runs their own ts-unplug, Aperture attributes the activity to individual users. If multiple people share a single ts-unplug instance, all activity appears under a single identity.

To set up ts-unplug on a device:

1. Clone the ts-plug repository from GitHub.
2. Build the ts-unplug application:
   1. Run make ts-unplug.
   2. Run make install.
3. Run the ts-unplug command to link to the Aperture proxy instance. Use the fully qualified domain name (FQDN) of the Aperture proxy and an available and accessible port number (for example, port 9996).

ts-unplug -dir ./state -port <PORT_NUMBER> ai.<YOUR_TAILNET_ID>.ts.net

Next, approve the device in the Machines of the admin console for the tailnet hosting Aperture. After you approve it, users on that device can access Aperture from http://localhost:<PORT_NUMBER>.