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 token, which Claude Code re-runs to refresh the bearer; aigw injects the upstream Anthropic key) is passed via claude --settings as a JSON string; off disk, merged on top of your settings, your ~/.claude/settings.json untouched. With an ADP API key the helper prints the stored key 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 gateway credential header in the environment: X-Redpanda-Api-Key with an ADP API key, else X-Redpanda-Cloud-Token (minted fresh at launch); 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).

In passthrough mode the X-Redpanda-Cloud-Token gateway JWT is set in the launched process environment, so Claude Code’s tool subprocesses (Bash, hooks, MCP) inherit it; the same Redpanda Cloud token any process running as you can already mint with rpk ai auth token, and Claude Code has no documented mechanism to scrub it from those subprocesses.

Because passthrough uses your real config home, any auth configured in your ~/.claude/settings.json (an apiKeyHelper, or env.ANTHROPIC_AUTH_TOKEN) still applies and outranks the subscription OAuth aigw needs to relay; rpk ai 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; aigw signs the upstream call with the provider’s AWS credentials (SigV4), so no AWS keys ever reach your machine and the managed apiKeyHelper auth works exactly as above (passthrough does not apply; there is no Bedrock analog of a Claude subscription). Pass -m an inference-profile id from the provider’s model allowlist (Bedrock Anthropic models 4.6+ carry a us./eu./apac./global. prefix). 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; aigw 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 claude-sonnet-4-6 -- --permission-mode plan
rpk ai run claude -L bedrock -m us.anthropic.claude-sonnet-4-6 -- -p "hi"
rpk ai run claude -L vertex -m claude-sonnet-4-6 -- -p "hi"

Usage

rpk ai run claude [flags]

Flags

Value Type Description

--api-key

string

authenticate the session with an ADP API key: ask (ask before creating one), yes (create one without asking, also without a terminal), no (always use your login token).

--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 the provider’s allowlist; for bedrock providers an inference-profile id like us.anthropic.claude-sonnet-4-6, for vertex providers a Claude model id like claude-sonnet-4-6); omit to let Claude Code pick its default.

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