Agentic Data Plane
beta

rpk ai run claude

Launch Anthropic’s Claude Code CLI with its model traffic routed through the Redpanda AI gateway for the active rpai profile.

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

  • passthrough (enterprise/Max subscription): your existing subscription login (stored under your config home) is used. rpai only sets the gateway base URL and the X-Redpanda-Cloud-Token header (minted fresh at launch) 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 (rpai 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 — rpai scrubs only the inherited shell env, not your on-disk settings.

Anthropic and Bedrock 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.

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"

Usage

rpk ai run claude [flags] [-- CLAUDE_ARGS...]

Flags

Value Type Description

--bedrock

-

force bedrock mode. Only needed when you have invoke-only access and rpai 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 (rpai never writes into it; the managed apiKeyHelper rides in --settings). Default: your real home, so trust/onboarding/theme/MCP all apply.

-h, --help

-

help for claude.

-L, --llmprovider

string

aigw LLM provider name to route through (an anthropic or bedrock 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); omit to let Claude Code pick its default.

--passthrough

-

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

--print-settings

-

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

-o, --format

string

output format: table|wide|json|yaml|markdown (env: RPAI_FORMAT) (default "table").

--no-color

-

disable colored output (env: NO_COLOR).

-c, --rpai-config

string

path to rpai config (env: RPAI_CONFIG) (default "/var/lib/redpanda/.rpai/config").

-s, --rpai-endpoint

string

override the selected environment’s AI Gateway URL for this invocation.

-p, --rpai-profile

string

rpai profile name (env: RPAI_PROFILE).

-v, --rpai-verbose

-

verbose debug logging to stderr (env: RPAI_VERBOSE).

--token

string

static bearer token override (ambient RPAI_TOKEN is ignored under rpk ai).