How to Run Claude Code and Codex CLI Through Bifrost CLI

TL;DR

• Bifrost CLI launches Claude Code, Codex CLI, OpenCode, and Gemini CLI with the gateway URL, credential, and model of a named context, and changes only the child process environment and temporary files.
• Install it with npx -y @maximhq/bifrost-cli, add a context with bifrost context add, store a virtual key, and run bifrost claude or bifrost codex.
• bifrost configure claude and bifrost configure codex write the same settings into the agents' own config files for direct use, with a receipt that bifrost unconfigure restores exactly.
• Verify with the launch banner, /status inside the agent, Bifrost request logs, and the Prometheus app label that names the calling agent.

Coding agents such as Claude Code and Codex CLI can send every model request to a gateway instead of directly to Anthropic or OpenAI, which gives a team one place to manage keys, budgets, models, and logs. Bifrost, the open-source AI gateway by Maxim AI, ships a CLI that does the wiring for you: it starts each agent pointed at the gateway with the right credential and model, and can remove that configuration as cleanly as it adds it. This tutorial installs Bifrost CLI, launches both agents through it, persists the setup for direct use, and verifies each request.

Why route Claude Code and Codex CLI through a gateway

Developers who search for a Claude Code proxy or an ANTHROPIC_BASE_URL setup usually want the same outcomes: one credential per developer instead of shared provider keys, spend limits that apply to agents, the freedom to use non-Anthropic or non-OpenAI models, and a log of what each agent sent. An AI gateway provides those in one layer for every agent.

Without a gateway, each developer configures each agent separately. Claude Code reads ANTHROPIC_BASE_URL and a token, Codex CLI needs a named provider in config.toml, and both pick up any stray ANTHROPIC_API_KEY or OPENAI_API_KEY already in the shell. Claude Code documents this pattern in its LLM gateway guide, and the Claude Code gateway comparison covers what to look for in the gateway itself.

Concern	Agent talking to a provider directly	Agent launched through Bifrost CLI
Credential	Provider API key or subscription login on each laptop	Bifrost virtual key or Enterprise SSO session, per context
Spend control	Provider account limits only	Virtual key budgets and rate limits
Models	That provider's catalog	Any model the virtual key allows, across providers
Audit	Provider console, per account	Bifrost request logs per key, user, model, and agent
Setup	Manual environment and config edits	One command per agent, reversible

Budgets and rate limits on agent traffic are set on the virtual key, and the AI governance page shows how those controls extend to teams and customers.

What Bifrost CLI does

Bifrost CLI is two tools in one binary. It is a launcher for coding agents (Claude Code, Codex CLI, OpenCode, and Gemini CLI) that routes them through Bifrost, and it is a scriptable client for inference, usage, and management APIs. Running bifrost with no command opens the interactive launcher; every other command works from a shell or CI job.

Figure 1: The CLI sets the gateway URL, credential, and model for the child process only, so the agent talks to Bifrost without editing your settings.

Each agent reaches the gateway on its own path:

Agent	Gateway path	Enterprise SSO	Virtual key	bifrost configure
Claude Code (claude)	/anthropic	Yes	Yes	Yes
Codex CLI (codex)	/openai/v1	Yes	Yes	Yes
OpenCode (opencode)	/openai	Yes	Yes	No
Gemini CLI (gemini)	/genai	No	Yes	No

The open-source gateway authenticates agents with virtual keys. Bifrost Enterprise adds SSO, so each request is attributed to the signed-in user, plus bifrost usage for personal budgets. The Bifrost CLI resource page summarizes both editions.

Step 1: Install Bifrost CLI

You need Node.js 18 or later and a running gateway. If you do not have one, the gateway setup guide starts Bifrost locally with npx -y @maximhq/bifrost. Then install the CLI:

npx -y @maximhq/bifrost-cli

The installer downloads the binary for your platform, verifies its SHA-256 checksum when one is published, and installs it to ~/.bifrost/bin/bifrost. On macOS and Linux it offers to add ~/.bifrost/bin to your PATH; on Windows, add %USERPROFILE%\.bifrost\bin yourself. Open a new terminal and check the install:

bifrost version
bifrost auth --help

To pin a release, pass --cli-version <version> to the installer, and run bifrost update later to upgrade. The Bifrost CLI getting started guide lists the credential types each edition supports.

Step 2: Add a context and store a virtual key

A context holds one gateway URL, an optional default model, launcher selections, and its own credentials in the operating-system keyring. Create one for your local gateway and make it current:

bifrost context add local --base-url http://localhost:8080 --use

Non-loopback URLs must use HTTPS; plain HTTP is accepted only for localhost, 127.0.0.1, and ::1. Next, create a virtual key in the dashboard under Governance → Virtual Keys, allow the providers and models your agents need, and store it without putting it in shell history:

printf '%s\n' "$BIFROST_VIRTUAL_KEY" | bifrost auth set-virtual-key --stdin

Leave out --stdin to type the key at a hidden prompt. If dashboard authentication is on and you want management commands, sign in with bifrost auth login --username admin --password-stdin. Then run the built-in check:

bifrost doctor
bifrost models list

bifrost doctor reports ok or failed for gateway health, management authentication, and model discovery with the current credential. bifrost models list shows only the models your virtual key can use, which is also the list the launcher offers. The OSS setup guide covers the same steps, and budgets and limits explains how to cap the key before handing it to an agent.

Step 3: Launch Claude Code through Bifrost

Start Claude Code with a model from the gateway:

bifrost claude --model anthropic/claude-sonnet-4-6

Before Claude Code starts, the CLI prints the endpoint, the credential type (virtual key or Enterprise SSO), and the equivalent command. Claude Code receives the gateway URL ending in /anthropic and the model. With a virtual key, the key is set in the child process environment only. With Enterprise SSO, Claude Code receives a temporary --settings file whose apiKeyHelper runs bifrost auth print-token, and that file is removed when Claude Code exits. Inherited ANTHROPIC_API_KEY or OPENAI_API_KEY values are removed from the child environment so they cannot override the Bifrost credential.

Arguments after the model pass through to Claude Code, so bifrost claude --resume resumes a session. Use -- before a Claude Code flag that clashes with a Bifrost flag.

Because the model name is a Bifrost model ID, Claude Code can run on models other than Anthropic's through the same command. Claude Code also maps its sonnet, opus, and haiku aliases through ANTHROPIC_DEFAULT_SONNET_MODEL and its siblings, which can name Bedrock or Vertex AI models such as bedrock/global.anthropic.claude-sonnet-4-6. The Claude Code integration docs cover alias mapping and MCP, and the multi-model routing walkthrough shows mixed-provider setups.

Claude Code sends x-claude-code-session-id on every request, so Bifrost keeps a session on the provider and key that served it and on the same prompt cache, with nothing to configure. The session affinity docs explain how that stickiness works.

Step 4: Launch Codex CLI through Bifrost

Codex CLI uses the OpenAI Responses API, and Bifrost connects it through a named custom provider. The CLI handles that for you:

bifrost codex --model openai/gpt-5

The launch runs Codex with a temporary CODEX_HOME that holds a copy of your config.toml plus a bifrost provider pointed at /openai/v1. The temporary home, including that session's history, is removed when Codex exits, and your normal Codex login stays untouched. Pass a task straight through with bifrost codex exec "summarize this repository".

To use a non-OpenAI model, pass its full Bifrost ID, for example bifrost codex --model anthropic/claude-opus-4-6. Bifrost translates Codex's Responses requests to the target provider, but the model must support the tool calls Codex relies on for file edits and shell commands, so check it before rolling it out:

bifrost models list --search claude-opus
bifrost codex --model anthropic/claude-opus-4-6

Two Codex details matter. Its in-session /model picker uses Codex's own catalog, not Bifrost's model list, so switch models by relaunching with --model and confirm with /status. And Codex sends a session-id header on every request, which gives it the same session affinity as Claude Code. The Codex CLI integration docs cover the remaining options, and the guide to Codex CLI beyond GPT walks through other model families. The tool itself is documented in OpenAI's Codex CLI docs.

Step 5: Persist configuration with bifrost configure

Launching through the CLI is the cleanest option, but some developers run claude or codex directly from an editor or a script. For them, bifrost configure writes the endpoint, virtual key, and optional model into the agent's own configuration:

bifrost configure claude --model anthropic/claude-sonnet-4-6
bifrost configure codex --model openai/gpt-5

Agent	Files changed
Claude Code	~/.claude/settings.json: env.ANTHROPIC_BASE_URL, env.ANTHROPIC_AUTH_TOKEN, model settings; removes apiKeyHelper
Codex CLI	~/.codex/auth.json and ~/.codex/config.toml with model_provider = "bifrost"

Before changing anything, the CLI saves a restoration receipt under ~/.bifrost/receipts/, written with owner-only permissions because it contains your original files and the virtual key. To undo the change:

bifrost unconfigure claude
bifrost unconfigure codex

Figure 2: Launches leave no trace after the agent exits; configure writes files you can roll back exactly from the receipt.

unconfigure restores the exact files captured before configuration. If you edited a configured file afterwards, both commands refuse to overwrite it unless you pass --force. configure requires a virtual key, because short-lived SSO tokens are never written to long-lived files. On Enterprise, a persisted ANTHROPIC_AUTH_TOKEN outranks the SSO helper that bifrost claude injects, so run bifrost unconfigure claude before switching to SSO. The coding agents guide documents the full behavior.

Verify requests reach Bifrost

A misconfigured agent often still works, because it falls back to a provider login or a stray key. Check four things in order.

Figure 3: Each check covers a different failure: wrong endpoint, wrong credential, missing request, or untracked usage.

1. Launch banner. endpoint shows your Bifrost URL and auth shows the expected credential type.
2. /status inside the agent. In Claude Code, the Status tab should show an Anthropic base URL ending in /anthropic and a credential line naming ANTHROPIC_AUTH_TOKEN or apiKeyHelper, not a claude.ai login. In Codex, /status should show the Bifrost model you launched.
3. Request logs. Send a short prompt, then run bifrost logs list --limit 5 or open Logs in the dashboard and confirm the request appears with the expected virtual key, provider, and model.
4. Metrics. Bifrost's Prometheus metrics carry an app label classified from the User-Agent, with values such as Claude Code, Codex CLI, Cursor, and API, so you can chart spend per agent:

sum by (app) (increase(bifrost_cost_total[1d]))

The AI observability page covers exporting the same data to OpenTelemetry and other backends, and the guide to governing Claude Code and Codex CLI shows how teams turn those numbers into policy.

Use contexts for staging, production, and CI

Contexts keep environments apart. Each context has its own credentials, so a staging key is never sent to production:

bifrost context add staging --base-url https://bifrost-staging.example.com
bifrost context add production --base-url https://bifrost.example.com --use

bifrost --context staging claude --model anthropic/claude-sonnet-4-6
bifrost claude --model anthropic/claude-sonnet-4-6   # uses production

Switching contexts switches every credential at once. To point at a different gateway, add a new context rather than running bifrost config set base-url, which keeps the stored credentials and sends them to the new URL.

In CI, skip the keyring and use environment variables from your secret store. BIFROST_BASE_URL and BIFROST_VIRTUAL_KEY override stored values, and bifrost codex exec runs a non-interactive task:

export BIFROST_BASE_URL=https://bifrost.example.com
export BIFROST_VIRTUAL_KEY="$CI_BIFROST_VIRTUAL_KEY"
bifrost codex --model openai/gpt-5 exec "run the tests and summarize failures"

Commands return stable exit codes (3 for an authentication failure, 6 for a timeout or unavailable gateway), which makes failures easy to branch on. The contexts and credentials guide lists every variable, and the Bifrost CLI overview shows how platform teams roll this out.

Troubleshooting Bifrost CLI with coding agents

Symptom	Likely cause	Fix
Claude Code opens its login screen	No Bifrost credential reached the session	Store a virtual key in the context, or set it in ~/.claude/settings.json, then restart
/status shows a claude.ai login	ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY outranks the helper, or a CLAUDE_CODE_USE_* variable is set	Remove them from settings and the shell; unset CLAUDE_CODE_USE_*
Codex still uses gpt-5 after /model	Codex's picker uses its own catalog	Relaunch with bifrost codex --model provider/model and check /status
Manually configured Codex ignores Bifrost	An OpenAI OAuth session takes precedence	Run /logout in Codex, or launch with bifrost codex
Model missing from the launcher	The virtual key does not allow it	Add the model to the virtual key, then rerun bifrost models list
configure refuses to run	The settings file changed after the last configure	Review the file, then rerun with --force

The CLI agents overview has per-agent limitations, and the Claude Code guides hub collects model-specific setups.

Frequently asked questions

Do I need a Claude Code proxy to use other models?

You need something that accepts Claude Code's Anthropic-format requests and forwards them to the model you choose. An AI gateway such as Bifrost does this on its /anthropic route and also applies keys, budgets, and logs. bifrost claude --model <provider/model> sets it up per session, as described in the Claude Code resource page.

What should ANTHROPIC_BASE_URL be set to for Bifrost?

Your gateway URL followed by /anthropic, for example https://bifrost.example.com/anthropic, with a virtual key in ANTHROPIC_AUTH_TOKEN. bifrost claude sets both for the session, and bifrost configure claude writes them to ~/.claude/settings.json.

Does bifrost claude change my Claude Code settings?

No. A launch changes only the child process environment and temporary files, which are removed when Claude Code exits. Only bifrost configure claude edits ~/.claude/settings.json, and it saves a receipt so bifrost unconfigure claude can restore the original file.

Can Codex CLI use Claude or Gemini models through Bifrost?

Yes, if the model supports the tool calls Codex needs. Launch with the full model ID, for example bifrost codex --model anthropic/claude-opus-4-6, and confirm the model with /status. Bifrost translates Codex's Responses API requests to the target provider. The Codex CLI integration post shows the manual setup.

Is Bifrost CLI available in the open-source version?

Yes. Contexts, the launcher, coding-agent launches, inference with a virtual key, and core management commands work with the open-source gateway. Enterprise adds SSO sign-in, per-user attribution, bifrost usage, and management commands for users, roles, and other Enterprise resources.

How do I see how much each coding agent costs?

Bifrost labels its Prometheus metrics with the calling app, so a query such as sum by (app) (increase(bifrost_cost_total[1d])) splits daily cost between Claude Code, Codex CLI, and other clients. Request logs show the same traffic per virtual key and model, and the Claude Code integration post covers what each log entry contains.

Put every coding agent behind one gateway

Bifrost CLI turns gateway setup for Claude Code and Codex CLI into one command per agent, keeps credentials per environment, and leaves nothing behind when a session ends. To roll it out across a team with SSO, budgets, and per-agent reporting, book a demo with the Bifrost team, or compare options in the Claude Code multi-model routing guide.