For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Configure the OpenCode AI coding agent to use agentgateway running in Kubernetes

Route LLM requests from OpenCode through agentgateway in Kubernetes. In this guide, OpenCode uses a virtual key, and the provider API key stays in a Kubernetes Secret.

Before you begin

1. Set up an agentgateway proxy.
2. Set up access to the OpenAI LLM provider. Use the OpenAI v1/chat/completions tab to create a route that allows requests to /v1/chat/completions.
3. Require virtual key authentication for the Gateway. This guide uses the vk-alice-4f9c2a example key. Token budgets are optional.
4. Install OpenCode. This guide was tested with OpenCode 1.18.35.

Set the gateway URL and virtual key

1. Set the base URL with the required /v1 suffix. Use INGRESS_GW_ADDRESS from the installation quickstart, or http://localhost:8080/v1 for port-forwarding.

   export AGENTGATEWAY_BASE_URL="http://${INGRESS_GW_ADDRESS}/v1"

2. Save the virtual key in an environment variable.

   export AGENTGATEWAY_API_KEY='vk-alice-4f9c2a'

Connect OpenCode to agentgateway

1. Create opencode.json in your project directory. For settings that apply to all projects, use ~/.config/opencode/opencode.json.

   cat > opencode.json <<'EOF'
   {
     "$schema": "https://opencode.ai/config.json",
     "model": "agentgateway/gpt-4o-mini",
     "provider": {
       "agentgateway": {
         "npm": "@ai-sdk/openai-compatible",
         "name": "Agentgateway",
         "options": {
           "baseURL": "{env:AGENTGATEWAY_BASE_URL}",
           "apiKey": "{env:AGENTGATEWAY_API_KEY}"
         },
         "models": {
           "gpt-4o-mini": {
             "name": "gpt-4o-mini"
           }
         }
       }
     }
   }
   EOF

   Setting	Description
   model	The default model, in <provider>/<model> format.
   provider.agentgateway.npm	The AI SDK package for an OpenAI-compatible API.
   options.baseURL	Reads the Gateway base URL from AGENTGATEWAY_BASE_URL.
   options.apiKey	Reads the virtual key from AGENTGATEWAY_API_KEY to keep it out of the file. You can also enter the key with OpenCode’s /connect command.
   models	The models that OpenCode can request. List only models that the Gateway allows.

2. Start OpenCode from the same directory.

   opencode

Verify the connection

1. Send a prompt in OpenCode, or run a single prompt from the command line:

   opencode run "Say hello"

2. Verify that the request appears in the agentgateway proxy logs.

   kubectl logs deployment/agentgateway-proxy -n agentgateway-system --since=5m \
     | grep 'http.path=/v1/chat/completions' \
     | tail -n 5

   A successful entry has http.status=200 and http.path=/v1/chat/completions.

If the virtual key is missing, unknown, or revoked, OpenCode shows the 401 response from the proxy.

Error: Unauthorized: api key authentication failure: invalid credentials

Next steps