Claude Code Runtime
Punk can sit under Claude Code in two stackable modes:
| Mode | Use it when |
|---|---|
| Model backend | You want Claude Code's Anthropic-compatible model traffic to flow through Punk. |
| MCP runtime tools | You want Claude to call Punk workflows, semantic web fetches, savings, approvals, and route explanations as tools. |
These modes can be used together. Claude stays the interface; Punk becomes the runtime layer underneath it.
Launch Claude Code Through Punk
Prerequisites: the Claude Code CLI on PATH, Punk hosted gateway access, and a tenant API key.
export PUNK_API_KEY=pk_...
bun run cli -- launch claude \
--gateway-url https://app.punktechnologies.com \
--api-key env:PUNK_API_KEY \
--model punk/chorus \
-- --print "summarize this repo"The launcher points Claude Code at Punk's Anthropic-compatible endpoint and clears parent-shell Anthropic credentials so model traffic cannot accidentally bypass the gateway.
Useful options:
| Option | Default | Meaning |
|---|---|---|
--model <id> | claude-sonnet-4-6 | Claude Code model id. Use punk/chorus for governed Chorus routing. |
--gateway-url <url> | https://app.punktechnologies.com | Punk hosted gateway receiving Claude's /v1/messages traffic. |
--api-key <token> | PUNK_API_KEY | Gateway bearer token when auth is enabled. |
--claude-bin <path> | claude | Claude Code executable. |
--dry-run | off | Print the resolved command and environment without launching Claude. |
Add Punk As An MCP Server
Register Punk's Runtime Engine MCP server with Claude Code:
claude mcp add punk --env PUNK_GATEWAY_URL=https://app.punktechnologies.com --env PUNK_MCP_API_KEY=$PUNK_API_KEY -- bun run --cwd /path/to/punk mcpVerify without Claude:
PUNK_GATEWAY_URL=https://app.punktechnologies.com PUNK_MCP_API_KEY=$PUNK_API_KEY bun run mcp --selfcheckThe MCP server exposes runtime tools for workflows, semantic web fetches, savings, approvals, and run explanations. It does not replace the gateway path; it gives Claude direct runtime tools in addition to model-backend routing.
What Punk Adds To Claude Code
| Capability | Result |
|---|---|
| Route visibility | Every Claude model request can become a Punk run with route explanation. |
| Governance | Policies and approvals can apply to tool and web side effects. |
| Cost control | Repeated compatible requests can hit cache or proven artifacts. |
| Evidence | Runs, receipts, trace events, and side-effect records stay inspectable. |
| Workflows | Claude can discover and run Punk workflows through MCP tools. |
Troubleshooting
| Symptom | Check |
|---|---|
| Claude Code talks directly to Anthropic | Start it through punk launch claude and verify ANTHROPIC_BASE_URL in --dry-run. |
| Tools do not appear | Run claude mcp list and bun run mcp --selfcheck. |
| No run appears in Punk | Confirm Claude traffic targets the Punk gateway origin, not Anthropic directly. |
| Auth fails | Pass --api-key env:PUNK_API_KEY or set PUNK_API_KEY consistently for the launcher and MCP runtime. |
Read next: Anthropic SDK, Chorus, OpenAI-Compatible AI Gateway.