Agentic Data Plane

Run OpenCode 2 through AI Gateway

Route OpenCode model requests through AI Gateway to use your team’s configured providers without managing upstream API keys on your workstation. You can switch between compatible models during a session, or authenticate with your own ChatGPT or Claude subscription where the provider permits it.

After reading this page, you will be able to:

  • Launch OpenCode 2 through an Agentic Data Plane LLM provider

  • Select and switch between compatible models in a session

  • Configure subscription authentication for OpenCode 2

Prerequisites

  • The rpk ai CLI, installed and signed in to the Agentic Data Plane environment you want to use. See Use the Agentic Data Plane CLI. Run rpk ai upgrade to update the plugin.

  • OpenCode 2.2.7 or later within major version 2, installed on your PATH. OpenCode 1 isn’t supported.

  • An enabled large language model (LLM) provider with at least one compatible model. Supported types include OpenAI, OpenAI-compatible, Anthropic, Google Gemini API, and Fireworks. You can also use Amazon Bedrock or Gemini Enterprise Agent Platform (formerly Vertex AI). See Configure an LLM Provider.

  • Permission to read and invoke the provider (dataplane_adp_llmprovider_get and dataplane_adp_llmprovider_invoke). OpenCode launches always need provider read access. See LLM provider permissions.

  • An Agentic Data Plane API key, or a Redpanda user who signs in directly and can create one (the Sandboxed permission template or higher). The launch can create or reuse a key for you. See How a session authenticates. A sign-in token doesn’t authenticate the OpenCode session itself.

Launch OpenCode

  1. Launch OpenCode from your project directory:

    rpk ai run opencode -L <provider-name>

    Replace <provider-name> with the name of your LLM provider, the segment after /providers/ in its Proxy URL. If you omit -L, the launcher prompts you to choose a provider.

  2. If prompted, approve creation of an Agentic Data Plane API key.

  3. Enter a prompt and confirm that OpenCode returns a model response. Run /models in OpenCode to choose another compatible model during the session.

The -m flag is optional and sets only the initial model. Without it, the session starts with the first compatible model in the provider’s allowlist. If the provider has no allowlist, it starts with the first compatible model in the server catalog.

OpenAI-compatible and Fireworks providers require an explicit model allowlist.

Every compatible model remains available through /models, including models that use a different API protocol. Title and compaction requests use the session’s initial model.

For example, to select the initial model explicitly:

rpk ai run opencode -L <provider-name> -m <model-id>

Replace <model-id> with an allowed, compatible model ID. For managed provider sessions, OpenCode addresses models as redpanda/<model-id>. Pass the model ID without that prefix to -m.

How the session is isolated

Each launch starts a private OpenCode session that only that launch uses. Your existing OpenCode background server isn’t used or changed, and the launcher refuses arguments that attach to another server.

Change to the intended project directory before you launch. The launcher refuses forwarded project-directory, worktree, and resume-session selectors, because its preflight checks only the launch directory.

Your agents, commands, Model Context Protocol (MCP) servers, and themes still apply. Before it acquires an API key, the launch checks your OpenCode configuration and active integration credentials. If provider configuration, credentials, or provider-access policies conflict with the session, the launch stops instead of using another route or authentication method.

OpenCode configuration and user plugins remain trusted local code. The private session isn’t an operating-system sandbox or a general network-egress restriction.

Check model compatibility

The launch configures each model from its supported API protocol and transport in the server catalog. It doesn’t choose one protocol for the whole provider. Catalog models must declare streaming, tool use, multi-turn conversations, and system prompts. The launch leaves incompatible or unknown models out with a diagnostic message and rejects one selected explicitly with -m.

Provider Compatible routes

OpenAI, OpenAI-compatible, Anthropic, Google Gemini API, and Fireworks

OpenAI Responses, OpenAI Chat Completions, Anthropic Messages, or Gemini Generate Content, as declared for the model and provider. OpenAI-compatible providers have no catalog entries. Ensure each allowlisted model supports Chat Completions and tool use.

Gemini Enterprise Agent Platform

Gemini Generate Content or Anthropic Messages for Claude models. The provider must have a project and location configured.

Amazon Bedrock

Bedrock Converse, or OpenAI Responses and Chat Completions over the provider’s supported Bedrock transport. Anthropic Messages through Bedrock InvokeModel isn’t a supported OpenCode route. A Claude model needs a compatible Converse binding instead.

For Amazon Bedrock and Gemini Enterprise Agent Platform, AI Gateway authenticates upstream requests using the provider’s stored credentials. You don’t need local Amazon Web Services (AWS) or Google Cloud credentials.

To inspect the generated configuration without starting OpenCode or creating a key, run:

rpk ai run opencode -L <provider-name> --print-config

This command still needs provider read access.

Use a ChatGPT subscription

This configuration refers to a third-party product. Specific UI elements may not be up to date. See OpenCode’s provider documentation.
  1. Configure an OpenAI provider with Authorization passthrough enabled and the base URL https://chatgpt.com/backend-api/codex. See Configure an LLM Provider.

  2. Sign in with OpenCode’s Codex browser method:

    opencode auth login openai --method chatgpt-browser

    For a device-code login instead, run:

    opencode auth login openai --method chatgpt-headless
  3. Launch the session:

    rpk ai run opencode -L <chatgpt-provider>

    Replace <chatgpt-provider> with the name of that passthrough provider.

OpenCode labels these Codex login methods as legacy, but they remain available in OpenCode 2. The separate chatgpt-token-sharing method targets a different upstream and doesn’t work with this provider’s Codex backend. The launcher refuses that method, an API-key login, or a missing subscription login. It checks active OpenCode 2 integration credentials, not the legacy auth.json import file.

This mode uses OpenCode’s native openai integration and offers only compatible Responses API models over HTTP. Your ChatGPT subscription determines which models you can use. A model in the gateway catalog or allowlist doesn’t grant subscription access to it.

OpenCode manages subscription authentication and refresh. It sends your subscription credential in Authorization, while a separate Agentic Data Plane API key authenticates to AI Gateway in X-Redpanda-Api-Key. The launcher doesn’t copy your subscription token into a generated file or static header.

Use a Claude Enterprise or Max subscription

This configuration refers to a third-party product. Specific UI elements may not be up to date. See Claude Code authentication.

Claude subscription use is subject to Anthropic’s terms and your subscription’s quotas. See Anthropic’s Agent SDK overview. The launcher doesn’t grant subscription entitlement or additional quota.

  1. Install the native claude executable, version 2.1.283 or later, on your PATH, and sign in with your subscription:

    claude auth login
  2. Configure an Anthropic provider with Authorization passthrough enabled. Leave its base URL unset or use https://api.anthropic.com.

  3. Launch OpenCode:

    rpk ai run opencode -L <claude-provider>

    Replace <claude-provider> with the name of that passthrough provider.

This mode uses OpenCode 2’s built-in claude-agent provider and your native Claude executable, and offers only compatible models that use the Anthropic Messages API. Claude owns its saved subscription login. A conflicting API-key or OAuth credential for this integration causes the launch to stop.

OpenCode’s permission controls apply to Claude subscription sessions, including its own --auto option. OpenCode disables Claude’s native tools, settings sources, hooks, and ambient MCP configuration. It bridges tool calls through OpenCode’s own tools and MCP machinery instead. Configure permissions in OpenCode, not through a separate Claude permission flag on rpk ai run. See OpenCode’s permission documentation.

The Claude subprocess receives the gateway URL and X-Redpanda-Api-Key separately from its subscription authentication. The launcher clears competing inherited Anthropic keys, tokens, headers, and cloud-mode overrides.

Protect the session credential

The launch passes the Agentic Data Plane API key in the OpenCode process’s REDPANDA_ADP_API_KEY environment variable. It doesn’t put the literal key in command arguments or generated configuration text. Both subscription modes require gateway authentication and an Agentic Data Plane API key. The upstream provider’s terms, available models, and subscription quotas still apply.

OpenCode receives a copy of the key at launch and doesn’t reread stored credentials. Renewing the stored key or switching environments or sign-ins doesn’t replace the key in a running OpenCode session. The gateway rejects the original key after expiry or revocation. Restart OpenCode to use a replacement key.

OpenCode resolves the deliberate credential placeholders when it loads configuration. Its private server’s resolved configuration can therefore contain the Agentic Data Plane API key in any session mode. Protect configuration APIs and diagnostic captures as credential-bearing data, and don’t share them. This exposure isn’t limited to Claude models or subscription sessions.

Run a single prompt

Pass OpenCode’s own arguments after a literal --. For example:

rpk ai run opencode -L <provider-name> --api-key=yes -- run "Summarize this repository"

The --api-key=yes flag allows creation of a key without an interactive prompt. To supply an existing key instead, pass --token with an Agentic Data Plane API key, not a sign-in token. If key acquisition fails, the launch stops rather than falling back to a sign-in token.

Troubleshooting

Symptom Action

The OpenCode command is unknown, or the installed version is unsupported

Run rpk ai upgrade to update the plugin. Use OpenCode 2.2.7 or later within major version 2 and confirm it is on your PATH.

The launch can’t read the provider

Grant dataplane_adp_llmprovider_get in addition to invoke access. The launcher requires provider read access even when you pass -L.

Models are missing from /models, or the launcher rejects an explicit model

Check the provider’s allowlist and the launch diagnostic. The model needs a supported API binding and the required capabilities. OpenAI-compatible and Fireworks providers need an explicit model allowlist.

Configuration, credentials, or provider-access policies conflict with the session

Remove or rename the conflicting entry identified by the launch error, then relaunch. Don’t bypass the isolation checks or manually copy subscription tokens into configuration.

The launch refuses a ChatGPT login

Sign in with chatgpt-browser or chatgpt-headless for the provider’s Codex backend. The chatgpt-token-sharing method and API-key logins don’t substitute for those methods.

A subscription model request fails upstream

Check that your subscription includes the selected model and hasn’t reached its quota. The gateway model list and Agentic Data Plane API key don’t change your subscription entitlement.

A Claude tool call needs approval

Use OpenCode’s permission controls. OpenCode bridges Claude tool calls through its own tool and MCP machinery rather than running Claude’s native tools.