Skip to main content
This guide provides instructions for integrating OpenCode with the TrueFoundry AI Gateway.

Quick setup

With OpenCode installed, install the setup tool, then run:
Select OpenCode and any other agents you want to configure. To set up only OpenCode, run:
Sign in to your organization, choose models and any MCP servers or Skills you need, then review and approve the changes. Follow the completion summary for any remaining steps. See Set Up Your IDEs for the full walkthrough. For manual configuration, follow the instructions below.

Prerequisites

Before integrating OpenCode with TrueFoundry, ensure you have:
  1. TrueFoundry Account: Create a TrueFoundry account and follow the instructions in our Gateway Quick Start Guide
  2. OpenCode Installation: Install OpenCode by following the official documentation

Integration Guide

This guide uses the OpenCode Desktop app for illustration, but the same configuration applies to the terminal-based (TUI) and IDE extension versions.

Step 1: Open Provider Settings

  1. Open the OpenCode Desktop app.
  2. Navigate to Providers in the left sidebar.
  3. Click + Connect next to Custom provider.
OpenCode Desktop Providers page with Custom provider highlighted at the bottom of the provider list

OpenCode Providers page showing Custom provider option

Step 2: Configure TrueFoundry as a Custom Provider

Fill in the following details in the Custom provider form:
  • Provider ID: tfy-gateway (or any identifier using lowercase letters, numbers, hyphens, or underscores)
  • Display name: truefoundry
  • Base URL: Your TrueFoundry AI Gateway URL (e.g., {GATEWAY_BASE_URL}). You can get this from the unified code snippet in the TrueFoundry AI Gateway Playground.
  • API key: Your TrueFoundry API key
OpenCode Custom provider configuration form showing Provider ID as tfy-gateway, Display name as truefoundry, and Base URL pointing to the TrueFoundry AI Gateway endpoint

Custom provider form with TrueFoundry configuration

TrueFoundry playground showing unified code snippet with base URL and model name

Get Base URL and API key from the unified code snippet

Step 3: Add Models

Scroll down in the Custom provider form to add models:
  1. In the Models section, enter the model ID from TrueFoundry (e.g., openai-main/gpt-5-codex) in the first field and a display name (e.g., tfy-gpt-5-codex) in the second field.
  2. Click + Add model to add more models as needed.
  3. Optionally, add custom Headers for tracking. For example, set application to opencode to tag all requests from OpenCode in TrueFoundry’s observability dashboard.
  4. Click Submit to save the configuration.
OpenCode Custom provider form showing model configuration with openai-main/gpt-5-codex as model ID, tfy-gpt-5-codex as display name, and a custom application header set to opencode

Adding models and custom headers in the Custom provider form

Minimum 128K context window requiredOpenCode includes a detailed system prompt with tool definitions, agent instructions, and project context that consumes a significant number of input tokens on every request.
  • Models with smaller context windows (e.g., 8K or 32K) will fail with prompt is too long errors
  • The system prompt combined with conversation history and tool call results quickly exceeds smaller limits
  • Refer to the OpenCode recommended models for models that are known to work well
Make sure the model you configure through the TrueFoundry AI Gateway supports at least 128K input tokens.

Step 4: Select a TrueFoundry Model and Start Coding

  1. In the OpenCode chat interface, click the model selector at the bottom of the screen.
  2. You will see your configured TrueFoundry models listed under the truefoundry provider.
  3. Select the model you want to use and start coding.
OpenCode model selector showing TrueFoundry models including tfy-claude-4-5, tfy-gpt-4o, tfy-gpt-5, tfy-gpt-5-codex, and tfy-gpt-5.2 under the truefoundry provider

TrueFoundry models available in OpenCode model selector

Alternative: Configuration via JSON

If you prefer configuring OpenCode through its JSON config file (useful for TUI or team-wide settings), add the following to your opencode.json:
Then set the default model to one of your TrueFoundry models:

Use Auto Routing

To route OpenCode requests by complexity, add an Auto Routing virtual model to models and select it like any other model:
OpenCode then calls one model name and the AI Gateway picks the model for each request.
  • What gets classified. OpenCode sends the whole conversation on every request. The classifier reads only the last user message and the last 2,000 characters of the system prompt. See what text gets classified.
  • Pinning. A session that moves to a higher tier stays on it, so a follow-up such as “thanks” does not drop back to a cheaper model. A new session starts from the classifier again. See conversation pinning.
  • Context window. Any tier can serve a request, so every model in every tier must meet the 128K minimum above.
  • Classifier. The benchmark favors Jev over the default heuristic for coding agents.
  • Prompt cache. A provider’s prompt cache belongs to one model, so a switch between tiers reads the history uncached. If cache stability matters more than cost per turn, use sticky routing or latency-based routing instead.
To check which tier served a request, see which tier served the request.

Observability and Governance

Monitor your OpenCode usage through TrueFoundry’s observability dashboard. With the application: opencode header configured, you can filter and analyze:
  • Performance Metrics: Track request latency, time to first token, and inter-token latency
  • Cost and Token Usage: Monitor input/output tokens and associated costs per model
  • Usage Patterns: Understand usage across models, users, and teams
  • Rate Limiting and Virtual Models: Set up rate limiting and configure Virtual Models for intelligent routing and fallback across your models

Fleet-wide enforcement

Gateway config: enforceable. OpenCode reads a managed configuration layer that users can’t modify: /Library/Application Support/opencode/ (macOS), /etc/opencode/ (Linux), %ProgramData%\opencode (Windows), or a macOS .mobileconfig profile in the ai.opencode.managed domain, which has the highest priority. Put the provider.<id>.options.baseURL, apiKey, and headers from the JSON configuration there, and optionally enabled_providers / disabled_providers so only the gateway provider exists. See OpenCode’s config and enterprise docs. MCP servers: enforceable. Remote servers are mcp.<name> entries with type: remote, url, headers, and optional oauth; point url at the MCP Gateway. Define them in the managed layer to pre-provision, and block others there with mcp.<name>.enabled: false or tool policies (tools: {"server_*": false}); there is no dedicated allowlist key. See OpenCode’s MCP servers doc.