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 dataplane secret store, usage rolls up on the Cost & Usage page, and no provider key or session token is written to disk.

After completing this guide, you will be able to:

  • Launch Claude Code through an Agentic Data Plane Anthropic or AWS Bedrock 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

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 or AWS Bedrock provider; Codex needs an OpenAI or OpenAI-compatible provider. To create one, see Configure an LLM provider.

  • The coding agent installed on your workstation:

  • 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 auth mode, also grant dataplane_adp_llmprovider_get; without read access, pass --passthrough for a passthrough provider or --bedrock for a Bedrock provider.

The rpk CLI starts the rpk ai plugin only after you have signed in to Redpanda Cloud. Before your first rpk ai command, run rpk cloud login --no-profile to sign in without selecting a cluster. This sign-in only unlocks the plugin. The rpk ai run command still authenticates with your separate rpk ai auth login credentials and its own Agentic Data Plane environment.

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. Required, and it must be an Anthropic or Bedrock provider.

  • -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.

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 auth modes. The choice determines who pays for the tokens.

Managed (API key)

The provider stores an Anthropic API key in the dataplane secret store, shown as API key reference on its Connection card. The gateway authenticates each request with your Redpanda token, 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 & 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 auth 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. 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 provider, with a warning.

Use an AWS 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., apac., 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 AWS Bedrock: 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 with your Redpanda token, exactly like a managed Anthropic provider, and the token refreshes for the whole session. 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.

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. 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 your Redpanda token, and the gateway injects the provider’s stored API key when one is configured.

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 <server-name> https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/<server-name>

In this URL, <cluster-id> is your dataplane’s cluster 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 & Usage under Governance in the sidebar, then filter by your provider. Within a few seconds, the requests from your coding-agent session appear, 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 refreshing the token for the whole session.

Troubleshooting

Symptom What to check

--llmprovider is required

The rpk ai run command needs the provider to route through. Pass -L <provider-name>, using the provider’s exact name.

Provider is the wrong type for the agent

Claude Code needs an Anthropic or Bedrock 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. An older rpk ai plugin also rejects Bedrock providers for Claude Code; update it with rpk ai upgrade.

Provider is disabled

The provider’s Status is not Active. Enable it with rpk ai llm 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

Sign in to Redpanda Cloud first with rpk cloud login --no-profile, then run rpk ai auth login. See the note under Prerequisites.

Unknown command error from rpk ai run

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

Passthrough session ends with an auth error partway through

A passthrough gateway 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.

MCP tool calls return OAuthConnectionRequired

You have not completed the consent flow for that MCP server. See User-delegated OAuth; Claude Code surfaces the authorization URL in the error so you can finish the handshake.

Next steps