{"slug":"use-opencode-with-aperture","title":"Use OpenCode with Aperture","tags":["tailscale"],"agent_summary":"Last validated: Apr 9, 2026","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Use OpenCode with Aperture\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\nConfigure [OpenCode](https://opencode.ai/) to send requests through [Aperture by Tailscale](https://tailscale.com/docs/aperture) so your organization gets centralized API key management, usage tracking, and session logging.\r\n\r\n## [Prerequisites](https://tailscale.com/docs/aperture/how-to/use-opencode\\#prerequisites)\r\n\r\nBefore you begin, you need:\r\n\r\n- An Aperture instance with at least one configured AI provider (such as Anthropic or OpenAI), accessible from your device. Refer to [get started with Aperture](https://tailscale.com/docs/aperture/get-started) if you have not set this up.\r\n- The Aperture host URL (default: `http://ai`) accessible from your device. Use `http://`, not `https://`.\r\n- [OpenCode](https://opencode.ai/) installed on your device.\r\n\r\nTo avoid unexpected TLS issues, use `http://` for the Aperture URL when configuring LLM clients. All connections remain encrypted using WireGuard, even when HTTPS is not used.\r\n\r\nAperture routes requests based on the model name, not the LLM client. Any LLM client configured to use Aperture can access any provider your admin has set up. Refer to the [provider compatibility reference](https://tailscale.com/docs/aperture/provider-compatibility) for the full list of supported providers and API formats.\r\n\r\n## [Configure OpenCode](https://tailscale.com/docs/aperture/how-to/use-opencode\\#configure-opencode)\r\n\r\nOpenCode requires two configuration changes: set the base URL to point at Aperture, and provide a placeholder API key for each provider.\r\n\r\n### [Set the base URL](https://tailscale.com/docs/aperture/how-to/use-opencode\\#set-the-base-url)\r\n\r\nPoint OpenCode at your Aperture instance by setting the base URL for each provider in the OpenCode configuration file.\r\n\r\n1. Open or create the OpenCode configuration file. The file is usually named `opencode.json` and located in your home directory or the directory where you run OpenCode. Refer to the [OpenCode configuration documentation](https://opencode.ai/docs/config/) for details.\r\n\r\n2. Add the following configuration to set Aperture as the base URL for your providers:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```json\r\n{\r\n \"$schema\": \"https://opencode.ai/config.json\",\r\n \"provider\": {\r\n \"anthropic\": {\r\n \"options\": {\r\n \"baseURL\": \"http://ai/v1\"\r\n }\r\n },\r\n \"openai\": {\r\n \"options\": {\r\n \"baseURL\": \"http://ai/v1\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\n\r\n\r\nReplace `http://ai` with your Aperture hostname. If you connect through ts-unplug, use `http://localhost:` instead.\r\n\r\nInclude only the providers you have configured in Aperture. For example, if you only have Anthropic configured, omit the `openai` block.\r\n\r\n3. Save the file.\r\n\r\n\r\n### [Configure authentication](https://tailscale.com/docs/aperture/how-to/use-opencode\\#configure-authentication)\r\n\r\nOpenCode requires an authentication entry for each provider. Set a placeholder value for each provider you configured.\r\n\r\nAperture identifies users through Tailscale identity and injects the real API credentials when forwarding requests. The placeholder value is never sent to the provider.\r\n\r\n1. Open or create the OpenCode authentication file.\r\n\r\n2. Add the following placeholder keys:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```json\r\n{\r\n \"anthropic\": {\r\n \"type\": \"api\",\r\n \"key\": \"-\"\r\n },\r\n \"openai\": {\r\n \"type\": \"api\",\r\n \"key\": \"-\"\r\n }\r\n}\r\n```\r\n\r\n\r\n\r\nThe dash character (`-`) satisfies OpenCode's authentication check.\r\n\r\n3. Save the file.\r\n\r\n\r\nAlternatively, enter the placeholder key interactively by running `/connect` inside OpenCode and selecting **Manually enter an API Key** for each provider.\r\n\r\n## [Verify the connection](https://tailscale.com/docs/aperture/how-to/use-opencode\\#verify-the-connection)\r\n\r\n1. Send a test message in OpenCode.\r\n2. Open the Aperture dashboard at `http://ai/ui/` and confirm the request appears on the **Logs** page.\r\n\r\nIf the request does not appear, refer to the [Aperture troubleshooting guide](https://tailscale.com/docs/aperture/troubleshooting).\r\n\r\n## [Next steps](https://tailscale.com/docs/aperture/how-to/use-opencode\\#next-steps)\r\n\r\n- [Grant model access to users](https://tailscale.com/docs/aperture/how-to/grant-model-access): Control which models each user or group can access through Aperture.\r\n- [View your usage dashboards](https://tailscale.com/docs/aperture/reference/dashboard): Monitor token consumption, costs, and session activity across your organization.\r\n- [Set per-user spending limits](https://tailscale.com/docs/aperture/how-to/set-per-user-spending-limits): Configure quota buckets to control costs for individual users.\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":"

Use OpenCode with Aperture

\n

Last validated: Apr 9, 2026

\n

Aperture by Tailscaleis currently in alpha.

\n

Configure OpenCode to send requests through Aperture by Tailscale so your organization gets centralized API key management, usage tracking, and session logging.

\n

Prerequisites

\n

Before you begin, you need:

\n\n

To avoid unexpected TLS issues, use http:// for the Aperture URL when configuring LLM clients. All connections remain encrypted using WireGuard, even when HTTPS is not used.

\n

Aperture routes requests based on the model name, not the LLM client. Any LLM client configured to use Aperture can access any provider your admin has set up. Refer to the provider compatibility reference for the full list of supported providers and API formats.

\n

Configure OpenCode

\n

OpenCode requires two configuration changes: set the base URL to point at Aperture, and provide a placeholder API key for each provider.

\n

Set the base URL

\n

Point OpenCode at your Aperture instance by setting the base URL for each provider in the OpenCode configuration file.

\n
    \n
  1. \n

    Open or create the OpenCode configuration file. The file is usually named opencode.json and located in your home directory or the directory where you run OpenCode. Refer to the OpenCode configuration documentation for details.

    \n
    2. \n
  2. \n

    Add the following configuration to set Aperture as the base URL for your providers:

    \n
    3. \n
\n
{\r\n     \"$schema\": \"https://opencode.ai/config.json\",\r\n     \"provider\": {\r\n       \"anthropic\": {\r\n         \"options\": {\r\n           \"baseURL\": \"http://ai/v1\"\r\n         }\r\n       },\r\n       \"openai\": {\r\n         \"options\": {\r\n           \"baseURL\": \"http://ai/v1\"\r\n         }\r\n       }\r\n     }\r\n}\n
\n

Replace http://ai with your Aperture hostname. If you connect through ts-unplug, use http://localhost:<PORT_NUMBER> instead.

\n

Include only the providers you have configured in Aperture. For example, if you only have Anthropic configured, omit the openai block.

\n
    \n
  1. Save the file.
    2. \n
\n

Configure authentication

\n

OpenCode requires an authentication entry for each provider. Set a placeholder value for each provider you configured.

\n

Aperture identifies users through Tailscale identity and injects the real API credentials when forwarding requests. The placeholder value is never sent to the provider.

\n
    \n
  1. \n

    Open or create the OpenCode authentication file.

    \n
    2. \n
  2. \n

    Add the following placeholder keys:

    \n
    3. \n
\n
{\r\n     \"anthropic\": {\r\n       \"type\": \"api\",\r\n       \"key\": \"-\"\r\n     },\r\n     \"openai\": {\r\n       \"type\": \"api\",\r\n       \"key\": \"-\"\r\n     }\r\n}\n
\n

The dash character (-) satisfies OpenCode's authentication check.

\n
    \n
  1. Save the file.
    2. \n
\n

Alternatively, enter the placeholder key interactively by running /connect inside OpenCode and selecting Manually enter an API Key for each provider.

\n

Verify the connection

\n
    \n
  1. Send a test message in OpenCode.
    2. \n
  2. Open the Aperture dashboard at http://ai/ui/ and confirm the request appears on the Logs page.
    3. \n
\n

If the request does not appear, refer to the Aperture troubleshooting guide.

\n

Next steps

\n\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}