Agentic Data Plane

rpk ai run claude

Launch Anthropic’s Claude Code CLI with its model traffic routed through the Redpanda AI gateway for the current rpk ai environment.

rpk ai points ANTHROPIC_BASE_URL at the gateway’s Anthropic Messages endpoint for the chosen provider and wires the gateway auth for the life of the session. No token is ever written to disk.

Both auth modes run in your REAL Claude Code config home, so your workspace trust, onboarding, theme, and MCP servers all apply. rpk ai writes nothing into ~/.claude in either mode:

  • managed (API key): the gateway apiKeyHelper (rpk ai auth api-key) prints the stored Agentic Data Plane API key; aigw injects the upstream Anthropic key. The helper is passed via claude --settings as a JSON string, off disk and merged on top of your settings. Your ~/.claude/settings.json remains untouched. An explicitly provided Agentic Data Plane API key uses the process environment instead.

  • passthrough (enterprise/Max subscription): your existing subscription login (stored under your config home) is used. rpk ai only sets the gateway base URL and the X-Redpanda-Api-Key gateway header in the environment; your subscription OAuth flows through aigw to Anthropic untouched.

Pass --claude-config-dir to run against an isolated config home instead of your real one (rpk ai still never writes into it).

Authenticated launches require an Agentic Data Plane API key. Account sign-in credentials serve only provider reads and API-key management; they are never passed to the model client. If key acquisition fails, rpk ai refuses to launch. --api-key=no requires an already provided Agentic Data Plane API key and never uses an account token. Passthrough’s gateway API key stays in the process environment, so Claude Code’s tool subprocesses (Bash, hooks, MCP) inherit it.

Because passthrough uses your real config home, any auth configured in your ~/.claude/settings.json (an apiKeyHelper, or env.ANTHROPIC_AUTH_TOKEN) still applies. It outranks the subscription OAuth aigw needs to relay. The command scrubs only the inherited shell env, not your on-disk settings.

Anthropic, Bedrock and Vertex providers are supported. A bedrock provider launches Claude Code in its native Bedrock mode pointed at the same gateway prefix. The gateway signs the upstream call with the provider’s AWS credentials (SigV4), so no AWS keys ever reach your machine. The managed apiKeyHelper auth works exactly as above. Passthrough does not apply, because there is no Bedrock analog of a Claude subscription. Pass -m a supported Anthropic Claude foundation model or inference-profile ID from the provider’s model allowlist (us./eu./apac./global. prefixes are supported; ARNs and other model families are not). If omitted, rpk ai selects the first compatible allowlisted Claude model. With invoke-only --bedrock access, rpk ai cannot verify the allowlist and keeps Claude Code’s default. Claude Code’s background (small/fast) model defaults to a Haiku-class inference profile in Bedrock mode; if the provider’s allowlist doesn’t include it, export ANTHROPIC_SMALL_FAST_MODEL with an allowlisted id.

A vertex provider launches Claude Code in its native Vertex mode pointed at the same gateway prefix, at the provider’s own project and location. The gateway signs the upstream call with the provider’s service account, so no Google credentials are needed on your machine. Auth works as for bedrock, and passthrough does not apply. Pass -m a Claude model id from the provider’s model allowlist. rpk ai must read the provider to learn its location, so a vertex provider needs read access, not only invoke access.

Pass Claude Code’s own flags after a literal --:

rpk ai run claude -L anthropic -m MODEL_ID -- --permission-mode plan
rpk ai run claude -L bedrock -m MODEL_ID -- -p "hi"
rpk ai run claude -L vertex -m MODEL_ID -- -p "hi"

Usage

rpk ai run claude [flags]

Flags

Value Type Description

--api-key

string

authenticate the session with an Agentic Data Plane API key: ask (ask before creating one), yes (create one without asking, also without a terminal), no (do not create a key; require an already provided Agentic Data Plane API key).

--bedrock

bool

force bedrock mode. Only needed when you have invoke-only access and rpk ai can’t read the provider to detect its type; when the provider can be read, its own type wins.

--claude-config-dir

string

run against this CLAUDE_CONFIG_DIR instead of your real/inherited config home (rpk ai never writes into it; the managed apiKeyHelper rides in --settings). Default: your real home, so trust/onboarding/theme/MCP all apply.

-L, --llmprovider

string

aigw LLM provider name to route through (an anthropic, bedrock or vertex provider).

-m, --model

string

model id to use (must be in any nonempty provider allowlist). Bedrock and Vertex require server-catalog Anthropic metadata and select the first compatible configured model when omitted (or the filtered server catalog when unrestricted). Invoke-only --bedrock requires an explicit model.

--passthrough

bool

force passthrough (enterprise/subscription) auth mode. Only needed when you have invoke-only access and rpk ai can’t read the provider to detect the mode; when the provider can be read, its own setting wins.

--print-settings

bool

print the generated Claude Code settings.json plus launch env, then exit (no claude needed). The provider type/mode resolve via a best-effort gateway lookup. Offline, the dump falls back to the managed anthropic shape, or bedrock with --bedrock.

Global flags

Value Type Description

--config

string

Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml.

-X, --config-opt

stringArray

Override rpk configuration settings; -X help for detail or -X list for terser detail.

--ignore-profile

bool

Ignore rpk.yaml and redpanda.yaml; use default settings.

--profile

string

rpk profile to use.

-v, --verbose

bool

Enable verbose logging.