Set up OpenCode with Aperture

OpenCode is a terminal coding agent that supports multiple AI providers. You can configure OpenCode to send requests through Aperture by Tailscale so that your organization benefits from centralized API key management, usage tracking, and session logging.

Prerequisites

• A running Aperture instance with at least one configured AI provider (such as Anthropic or OpenAI). Refer to Get started with Aperture if you haven't set up Aperture yet.
• Make sure the Aperture host URL (default: http://ai) is accessible on the network. Use http:// instead of https:// to avoid TLS issues.
• OpenCode installed on your device.

Configure the base URL

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

1. Open or create the OpenCode configuration file at the following path:

   ~/.opencode/opencode.json
   

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

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

   Replace http://ai with your Aperture hostname if you use a different MagicDNS name. Use the same baseURL for all providers. For additional providers, add a matching block with the same baseURL. Refer to Aperture for the full list of supported providers.

Configure authentication

OpenCode requires an authentication entry for each provider, even though Aperture injects the real credentials when forwarding requests. Aperture identifies users through Tailscale identity and never forwards the placeholder value to the AI provider.

1. Open or create the OpenCode authentication file at the following path:

   ~/.local/share/opencode/auth.json
   

2. Add the following placeholder keys:

   {
     "anthropic": {
       "type": "api",
       "key": "-"
     },
     "openai": {
       "type": "api",
       "key": "-"
     }
   }
   

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

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

Verify the connection

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

Troubleshooting

If the request does not appear in the Aperture logs:

• Confirm the baseURL in opencode.json matches your Aperture hostname.
• Confirm the auth file contains a placeholder key for the provider you used.
• Verify your device can reach Aperture by opening http://ai/ui/ in a browser.

For additional help, refer to Aperture troubleshooting.