Agentic Data Plane

Run Claude Code and Codex through AI Gateway

Claude Code and Codex are command-line coding agents. The rpk ai command launches either one with its model traffic routed through an AI Gateway provider, reusing your rpk ai sign-in so you don’t set base URLs or mint tokens by hand. Your team’s coding agent calls then flow through Agentic Data Plane: provider credentials stay in the Agentic Data Plane secret store, usage rolls up on the Cost and usage page, and no upstream provider key reaches your machine.

After completing this guide, you will be able to:

Launch Claude Code through an Agentic Data Plane Anthropic, Amazon Bedrock, or Vertex AI provider with rpk ai run claude
Launch Codex through an Agentic Data Plane OpenAI provider with rpk ai run codex
Choose between a managed (API-key) provider and an enterprise passthrough (subscription-seat) provider for Claude Code

Request flow from Claude Code or Codex through rpk ai run and AI Gateway to a compatible LLM provider. The coding agent receives model responses while provider credentials remain in the Agentic Data Plane secret store and usage flows to Cost and Usage.

Figure 1. rpk ai run routes coding agent model traffic through AI Gateway

Prerequisites

The rpk ai CLI, installed and signed in to the Agentic Data Plane environment whose gateway you want to target. See Use the Agentic Data Plane CLI. The rpk ai run command uses the credentials from rpk ai auth login, not a rpk cloud session.
An enabled large language model (LLM) provider of the matching type. Claude Code needs an Anthropic, Amazon Bedrock, or Google Cloud Vertex AI provider. The Agentic Data Plane UI lists the Vertex AI type as Gemini Enterprise Agent Platform. Codex needs an OpenAI or OpenAI-compatible provider. To create one, see Configure an LLM provider.
The coding agent installed on your workstation:
- Claude Code. See Anthropic’s Claude Code documentation.
- Codex. See OpenAI’s Codex documentation. The rpk ai run codex command needs a recent Codex version and tells you when yours is too old.
A Redpanda service account or user with permission to invoke the provider (dataplane_adp_llmprovider_invoke). See LLM provider permissions. To let rpk ai run claude read the provider and auto-detect its type and authentication mode, also grant dataplane_adp_llmprovider_get; without read access, pass --passthrough for a passthrough provider or --bedrock for a Bedrock provider. A Vertex AI provider needs read access, because the launch has to read the provider’s project and location.

Run Claude Code

Launch Claude Code with its traffic routed through an Anthropic provider:

rpk ai run claude -L <anthropic-provider> -m <model>

In this command, <anthropic-provider> is the name of your Anthropic provider (the segment after /providers/ in its Proxy URL), and <model> is a model the provider allows. The flags work as follows:

-L, --llmprovider: The provider to route through. It must be an Anthropic, Bedrock, or Vertex AI provider. Omit the flag to pick from the enabled providers of those types. The launch takes the only one it finds, or asks you to choose when there are several. Where nothing can answer that prompt, such as in a script, pass the flag.
-m, --model: The model to use. Omit it to let Claude Code pick its default.

Flags before a literal -- configure rpk ai run itself. Everything after -- is passed straight through to Claude Code, so you can set any of its own flags. For example, to start Claude Code in plan mode:

rpk ai run claude -L <anthropic-provider> -m claude-sonnet-4-6 -- --permission-mode plan

Claude Code starts in your real configuration home, so your workspace trust, onboarding, theme, and Model Context Protocol (MCP) servers all apply, and nothing is written into ~/.claude.

Your own provider routing doesn’t apply to the session. A workstation set up to run Claude Code against your own Amazon Bedrock account or Google Cloud Vertex AI project sets the transport-mode variables that pick those routes. The rpk ai run claude command overrides them for the session and ignores the inherited values, so the traffic still reaches the gateway. Each mode is turned off unless you launch against a provider of that type, and pointed at the gateway when you do. A Vertex AI launch also overrides your own Google Cloud project and region settings, including the per-model region variables, so every call goes to the provider’s own project and location. In enterprise passthrough mode, the launch can’t override those settings, so it stops with an error instead when the env block of a Claude Code settings.json turns on CLAUDE_CODE_USE_BEDROCK or CLAUDE_CODE_USE_VERTEX. The error names the setting to remove.

Choose managed or enterprise passthrough

For an Anthropic provider, the rpk ai run claude command reads its Auth passthrough setting and picks one of two authentication modes. The choice determines who pays for the tokens.

Managed (API key): The provider stores an Anthropic API key in the Agentic Data Plane secret store, shown as API key reference on its Connection card. The gateway authenticates each request with the session’s Agentic Data Plane credential, injects the stored key, and forwards the call to Anthropic. Tokens are billed as API usage against the account that owns that key, and per-model spend appears on the provider’s Overview tab. You need no Anthropic credential of your own.
Enterprise passthrough (subscription): The provider has Auth passthrough enabled and stores no API key. Claude Code signs in with your own Claude subscription (Max, Team, or Enterprise), and rpk ai run claude forwards that subscription login to Anthropic unchanged. Tokens are billed against your subscription seat, not as per-token API usage. Agentic Data Plane authenticates your organization with a separate gateway credential that rpk ai run sets for you, so the call is still observed on the Cost and usage page while the subscription bears the cost.

When rpk ai run claude cannot read the provider (invoke-only access), it cannot detect the provider’s type or authentication mode, and it launches in managed Anthropic mode by default. Pass --passthrough to force passthrough for a subscription provider, or pass --bedrock for a Bedrock provider. A Vertex AI provider has no such flag, because the launch has to read the provider’s location, so grant read access instead. When the provider is readable, its own type and setting win: the launch ignores a contradicting --passthrough on a managed Anthropic provider, or a contradicting --bedrock on an Anthropic or Vertex AI provider, with a warning.

Use an Amazon Bedrock provider

Claude Code can also route through a Bedrock provider, running in its native Bedrock mode:

rpk ai run claude -L <bedrock-provider> -m us.anthropic.claude-sonnet-4-6

In this command, <bedrock-provider> is the name of your Bedrock provider. For -m, pass an inference-profile ID the provider allows: a model identifier with a region prefix such as us., eu., or global.. Bedrock requires an inference profile for Claude 4.6 and later models; older models also accept bare foundation-model IDs. For selection guidance, see Inference profiles and IAM.

AI Gateway signs each upstream call with the AWS credentials stored on the provider, so no AWS keys reach your machine. The session authenticates to the gateway exactly like a managed Anthropic provider. See How a session authenticates. Enterprise passthrough does not apply to Bedrock. A Claude subscription has no Bedrock analog, so --passthrough fails with an error.

In Bedrock mode, Claude Code runs background tasks on a Haiku-class model by default. If the provider’s allowlist does not include one, set ANTHROPIC_SMALL_FAST_MODEL to an allowlisted inference-profile ID before you launch.

Use a Google Cloud Vertex AI provider

Claude Code can also route through a Vertex AI provider, which the Agentic Data Plane UI lists as Gemini Enterprise Agent Platform. The session runs in Claude Code’s native Vertex mode:

rpk ai run claude -L <vertex-provider> -m claude-sonnet-4-6

In this command, <vertex-provider> is the name of your Vertex AI provider. For -m, pass a Claude model ID the provider allows, such as claude-sonnet-4-6.

The session runs against the provider’s own Google Cloud project and location. AI Gateway signs each upstream call with the service account stored on the provider, so no Google Cloud credentials are needed on your machine, and the session authenticates to the gateway exactly like a managed Anthropic provider. Enterprise passthrough does not apply to Vertex AI. A Claude subscription has no Vertex AI analog, so --passthrough fails with an error.

The launch reads the provider to learn its project and location, so a Vertex AI provider needs read access (dataplane_adp_llmprovider_get) and not only invoke access. With invoke-only access, the launch warns, falls back to the managed Anthropic shape, and the gateway rejects the first request.

The Agentic Data Plane UI writes this launch command for you, on the provider’s Connect tab and under Use with rpk ai in the provider page header. Both fill in the provider name and pass the first Claude model the provider allows with -m, or leave -m off when the provider doesn’t restrict models. A provider whose model list holds no Claude model offers no Claude Code launch.

Run Codex

Launch Codex with its traffic routed through an OpenAI or OpenAI-compatible provider:

rpk ai run codex -L <openai-provider> -m <model>

In this command, <openai-provider> is the name of your OpenAI or OpenAI-compatible provider, and <model> is a model the provider allows. Only OpenAI and OpenAI-compatible providers work, because Codex speaks the OpenAI Responses API. As with Claude Code, you can omit -L and pick from the enabled providers of those two types. Codex also takes a reasoning-effort flag, -e (--effort), which accepts minimal, low, medium, or high. Omit it to let Codex use its default.

As with Claude Code, everything after a literal -- is passed straight through to Codex. For example, to skip Codex’s approval prompts:

rpk ai run codex -L <openai-provider> -m gpt-5.3-codex -e high -- --ask-for-approval never

Codex runs against a throwaway configuration home, so your own ~/.codex is never read or modified. The launch directory is auto-trusted under a workspace-write sandbox, so Codex does not prompt for trust on every run. Pass --no-auto-trust to keep Codex’s normal first-run trust prompt, for example, when you launch inside a freshly cloned repository.

Codex has no passthrough mode. Every Codex session authenticates to the gateway with its Agentic Data Plane credential, and the gateway injects the provider’s stored API key when one is configured.

How a session authenticates

A session authenticates to AI Gateway with an Agentic Data Plane API key, so it keeps working after the sign-in token that started it expires. Starting a session still needs a valid sign-in.

The first launch in an environment asks whether to create a key. Answer yes and rpk ai run creates one that is valid for 30 days and stores it alongside your rpk ai credentials, under the organization and environment you launched in. The key’s name records the command and your hostname.

A later launch reuses that key until the last tenth of its lifetime, which is three days of a 30-day key, and then replaces it. It also replaces a key that has expired or that no longer exists in the environment. A replaced key stays valid until it expires, so a session still running on it isn’t cut off.

The key a session uses is pinned to the organization and environment you launched in. Switching environments with rpk ai env use or signing in to another organization doesn’t change the key a running session uses. If a different sign-in replaces the stored key for that environment while your session runs, the session stops with an error asking you to restart it, rather than carrying on as that other user.

The --api-key flag chooses the behavior for both rpk ai run claude and rpk ai run codex:

ask (the default): Ask before creating a key.
yes: Create a key without asking. Use this where nothing can answer a prompt, such as a script or an IDE task.
no: Authenticate the session with your sign-in token instead.

A session falls back to your sign-in token, and says why, in these cases:

You decline the prompt, or nothing can answer it and you didn’t pass --api-key=yes.
The environment doesn’t issue API keys yet.
You can’t create an API key in the environment. Agentic Data Plane issues API keys only to users who sign in directly.
The file holding the stored key can’t be read, or your sign-in can’t use the stored key.
You passed --token, so the launch already has a credential.

A sign-in token expires at a fixed time, which matters most in enterprise passthrough mode. That session carries the credential it was launched with and can’t pick up a fresh one. In every other mode, a session running on a sign-in token refreshes that token for as long as the session lasts.

Make it a shortcut

If you launch the same agent and provider often, define a shell alias so the launch becomes a short command. Anything after -- is passed to the agent, so you can pin your own agent flags in the alias too. For example, to launch Claude Code through your provider with your preferred model every time:

Bash or Zsh
fish

Add the alias to ~/.bashrc or ~/.zshrc:

alias claude-gw='rpk ai run claude -L <anthropic-provider> -m claude-sonnet-4-6'

Define a saved alias (fish persists it as a function):

alias --save claude-gw 'rpk ai run claude -L <anthropic-provider> -m claude-sonnet-4-6'

Attach Agentic Data Plane-hosted MCP servers (optional)

Claude Code can call MCP servers for tool access. To use the MCP servers you host in Agentic Data Plane (managed catalog types, self-managed proxied servers, or both), register each one with Claude Code:

claude mcp add --transport http <server-name> https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/<server-name>

In this URL, <cluster-id> is your cluster’s identifier, and <server-name> is the MCP server’s name in Agentic Data Plane. For OAuth-protected MCP servers (most managed types), Claude Code prompts you to complete the consent flow on first use. Agentic Data Plane stores the resulting token in the per-user token vault, so later invocations reuse it.

If a server exposes a large tool catalog, turn on code mode and point Claude Code at the server’s code-mode endpoint to cut the token cost of loading every tool definition.

Observe usage

Open Cost and usage in the sidebar, then click the Providers tab of the Spend breakdown table. Within a few seconds, the requests from your coding agent session appear on your provider’s row, and the provider’s Overview tab breaks spend down per model.

Ad-hoc rpk ai run sessions are not registered agents, so they do not appear in the per-agent Transcripts view. Transcripts cover agents you create in Agentic Data Plane.

Configure the agent by hand

The rpk ai run command is for interactive command-line work. For CI runners, headless jobs, and application code, authenticate with the OIDC client_credentials grant and set the agent’s base URL and token yourself. For the full flow, with the Proxy URL anatomy, the token mint, and SDK examples, see Connect your app to AI Gateway. For a managed Anthropic provider, set the variables and launch the agent directly:

export ANTHROPIC_BASE_URL="https://aigw.<cluster-id>.clusters.rdpa.co/llm/v1/providers/<anthropic-provider>"
export ANTHROPIC_AUTH_TOKEN="<oidc-access-token>"
claude

In this example, <oidc-access-token> is an access token minted with the client_credentials grant. It has a short lifetime, and AI Gateway does not refresh it for you, so re-mint it when it expires. The rpk ai run command avoids this by authenticating the session with a long-lived API key, or by refreshing your sign-in token when it runs without one.

Troubleshooting

Symptom What to check

Symptom	What to check
`--llmprovider is required`	More than one provider can serve the launch, and there’s no terminal to offer the choice on, which is what happens in a script or a CI job. Pass `-L <provider-name>`, using the provider’s exact name.
`you cannot list LLM providers in this environment`	You omitted `-L`, and you don’t have permission to list the environment’s providers, so the launch can’t find one for you. Pass `-L <provider-name>`, using the provider’s exact name.
`no enabled ... provider`	You omitted `-L`, and the environment has no enabled provider of a type the agent can use. Create or enable one, or pass `-L <provider-name>`.
`rpk is not on PATH`	The session’s auth helper runs `rpk ai auth`, so the launch has to find `rpk`. The launch uses the `rpk` that started it where it can, and otherwise the first one on your PATH. Add `rpk` to your PATH, then relaunch. An enterprise passthrough session registers no auth helper, so it doesn’t fail this way.
Provider is the wrong type for the agent	Claude Code needs an Anthropic, Bedrock, or Vertex AI provider, and Codex needs an OpenAI or OpenAI-compatible provider. Confirm the Type on the provider’s Connection card, and pass a provider of the matching type to `-L`. A Vertex AI provider’s type reads Gemini Enterprise Agent Platform. An older `rpk ai` plugin also rejects Bedrock or Vertex AI providers for Claude Code; update it with `rpk ai upgrade`.
A Vertex AI session is rejected by the gateway on its first request	The launch could not read the provider, so it fell back to the Anthropic shape instead of Vertex mode, and it warned when it did. Grant read access to the provider (`dataplane_adp_llmprovider_get`), then relaunch. No flag substitutes for read access on a Vertex AI provider, because the launch has to read the provider’s project and location.
A Vertex AI session fails with a location mismatch	A per-model Vertex AI region variable in your environment named a location the provider doesn’t serve, and a newer Claude Code release added that variable name after the launch learned to override it. Unset the variable, or update the `rpk ai` plugin with `rpk ai upgrade`, then relaunch. The request is refused at the gateway, so it never reaches Vertex AI.
Provider is disabled	The provider’s `Status` shows `Disabled`. Enable it with `rpk ai llm-provider update <provider-name> --enabled`, or from the provider detail page.
`no usable gateway token`	The cached `rpk ai` credentials are missing or expired. Run `rpk ai auth login` to refresh them, then relaunch. The error’s `rpai auth login` hint refers to the same sign-in.
The session hangs, or the agent reports that the model is not allowed for the provider (HTTP 403)	The model you passed to `-m` is not in the provider’s allowlist. Claude Code retries the rejected requests silently, so the session can appear to hang; when `rpk ai run claude` can read the provider, the launch warns you and names the allowed models. Open the provider detail page, confirm the model row appears, and pass that exact identifier. For a Bedrock provider, that identifier is an inference-profile ID.
Missing `claude` or `codex` binary on the `PATH`	The agent binary is not installed or not on your `PATH`. Install it (see Prerequisites), then relaunch.
Sign-in required before `rpk ai` starts	Run `rpk ai auth login` to sign in and select an Agentic Data Plane environment.
Unknown command error from `rpk ai run`	Your `rpk ai` plugin predates `rpk ai run`. Update it with `rpk ai upgrade`, then relaunch.
A passthrough session authenticates with an API key or token instead of your Claude subscription	An `apiKeyHelper` or `env.ANTHROPIC_AUTH_TOKEN` entry in your `~/.claude/settings.json` still applies in passthrough mode and takes precedence over your subscription sign-in. The launch clears these from your shell environment only, not from your settings files. Remove the entry from `settings.json`, then relaunch.
Passthrough session ends with an authentication error partway through	A passthrough session carries the credential it was launched with, and a sign-in token cannot refresh mid-session. When `rpk ai run claude` warns that the token expires soon, run `rpk ai auth login` for a full-length session before relaunching. A session that authenticates with an API key isn’t affected, because the key outlives the sign-in. See How a session authenticates.
The launch stops because your Claude Code settings would route the session to your own provider	A `settings.json` that applies to this launch turns on `CLAUDE_CODE_USE_BEDROCK` or `CLAUDE_CODE_USE_VERTEX` in its `env` block. The launch reads the one in your Claude Code configuration home and the `.claude/settings.json` and `.claude/settings.local.json` files in the directory you launch from. Remove the entry, or set it to `0`, then relaunch. Only an enterprise passthrough session stops for this. The other modes override the setting for the session instead, so the traffic still reaches the gateway.
MCP tool calls fail with a `connection_required` error	You have not completed the consent flow for that MCP server. The failed tool result carries the authorization URL. Open it to connect, then call the tool again. See User-delegated OAuth.

--llmprovider is required

More than one provider can serve the launch, and there’s no terminal to offer the choice on, which is what happens in a script or a CI job. Pass -L <provider-name>, using the provider’s exact name.

you cannot list LLM providers in this environment

You omitted -L, and you don’t have permission to list the environment’s providers, so the launch can’t find one for you. Pass -L <provider-name>, using the provider’s exact name.

no enabled ... provider

You omitted -L, and the environment has no enabled provider of a type the agent can use. Create or enable one, or pass -L <provider-name>.

rpk is not on PATH

The session’s auth helper runs rpk ai auth, so the launch has to find rpk. The launch uses the rpk that started it where it can, and otherwise the first one on your PATH. Add rpk to your PATH, then relaunch. An enterprise passthrough session registers no auth helper, so it doesn’t fail this way.

Provider is the wrong type for the agent

Claude Code needs an Anthropic, Bedrock, or Vertex AI provider, and Codex needs an OpenAI or OpenAI-compatible provider. Confirm the Type on the provider’s Connection card, and pass a provider of the matching type to -L. A Vertex AI provider’s type reads Gemini Enterprise Agent Platform. An older rpk ai plugin also rejects Bedrock or Vertex AI providers for Claude Code; update it with rpk ai upgrade.

A Vertex AI session is rejected by the gateway on its first request

The launch could not read the provider, so it fell back to the Anthropic shape instead of Vertex mode, and it warned when it did. Grant read access to the provider (dataplane_adp_llmprovider_get), then relaunch. No flag substitutes for read access on a Vertex AI provider, because the launch has to read the provider’s project and location.

A Vertex AI session fails with a location mismatch

A per-model Vertex AI region variable in your environment named a location the provider doesn’t serve, and a newer Claude Code release added that variable name after the launch learned to override it. Unset the variable, or update the rpk ai plugin with rpk ai upgrade, then relaunch. The request is refused at the gateway, so it never reaches Vertex AI.

Provider is disabled

The provider’s Status shows Disabled. Enable it with rpk ai llm-provider update <provider-name> --enabled, or from the provider detail page.

no usable gateway token

The cached rpk ai credentials are missing or expired. Run rpk ai auth login to refresh them, then relaunch. The error’s rpai auth login hint refers to the same sign-in.

The session hangs, or the agent reports that the model is not allowed for the provider (HTTP 403)

The model you passed to -m is not in the provider’s allowlist. Claude Code retries the rejected requests silently, so the session can appear to hang; when rpk ai run claude can read the provider, the launch warns you and names the allowed models. Open the provider detail page, confirm the model row appears, and pass that exact identifier. For a Bedrock provider, that identifier is an inference-profile ID.

Missing claude or codex binary on the PATH

The agent binary is not installed or not on your PATH. Install it (see Prerequisites), then relaunch.

Sign-in required before rpk ai starts

Run rpk ai auth login to sign in and select an Agentic Data Plane environment.

Unknown command error from rpk ai run

Your rpk ai plugin predates rpk ai run. Update it with rpk ai upgrade, then relaunch.

A passthrough session authenticates with an API key or token instead of your Claude subscription

An apiKeyHelper or env.ANTHROPIC_AUTH_TOKEN entry in your ~/.claude/settings.json still applies in passthrough mode and takes precedence over your subscription sign-in. The launch clears these from your shell environment only, not from your settings files. Remove the entry from settings.json, then relaunch.

Passthrough session ends with an authentication error partway through

A passthrough session carries the credential it was launched with, and a sign-in token cannot refresh mid-session. When rpk ai run claude warns that the token expires soon, run rpk ai auth login for a full-length session before relaunching. A session that authenticates with an API key isn’t affected, because the key outlives the sign-in. See How a session authenticates.

The launch stops because your Claude Code settings would route the session to your own provider

A settings.json that applies to this launch turns on CLAUDE_CODE_USE_BEDROCK or CLAUDE_CODE_USE_VERTEX in its env block. The launch reads the one in your Claude Code configuration home and the .claude/settings.json and .claude/settings.local.json files in the directory you launch from. Remove the entry, or set it to 0, then relaunch. Only an enterprise passthrough session stops for this. The other modes override the setting for the session instead, so the traffic still reaches the gateway.

MCP tool calls fail with a connection_required error

You have not completed the consent flow for that MCP server. The failed tool result carries the authorization URL. Open it to connect, then call the tool again. See User-delegated OAuth.

Next steps

Was this helpful?

group Ask in the community

mail Share your feedback