qbraid-code

Use Claude Code through the qBraid AI gateway.

Install qbraid-code without Node.js or administrator rights. Create a separate API-key profile for each qBraid organization. The statusline shows the bound organization, its credit balance, the model, and context use.

Install

macOS and Linux

curl -fsSL https://qbraid.com/code.sh | bash

Windows PowerShell

irm https://qbraid.com/code.ps1 | iex

An install without --profile creates the default profile. To add another organization, run the installer again with a new profile name.

curl -fsSL https://qbraid.com/code.sh | bash -s -- --profile research

& ([scriptblock]::Create((irm https://qbraid.com/code.ps1))) -Profile research

The installer uses the authenticated organization name when the API returns one. Otherwise, set a readable local name before you run the installer.

export QBRAID_CODE_PROFILE_LABEL="Research Lab"

$env:QBRAID_CODE_PROFILE_LABEL = 'Research Lab'

The statusline marks a user-provided name as local. When available, it also shows a shortened verified organization ID.

Older installs that use one account migrate to profiles/default once. Migration does not overwrite an existing profile. A running legacy proxy keeps its private config until it exits. The next launch removes the retired secret files.

Keep Claude Code compatible

qbraid-code supports Claude Code 2.1.186 or newer. It is tested through 2.1.238. The installer checks both the version and required HTTP MCP commands.

Set QBRAID_CODE_CLAUDE_POLICY before installation to control an incompatible Claude Code installation.

Value	Installer behavior
prompt	Ask before installing or upgrading. Fail without a terminal.
upgrade	Install Anthropic's stable channel without prompting.
fail	Stop without changing Claude Code.
continue	Keep the installed version and skip unavailable features.

The installer never downgrades a newer or unrecognized version. If your version cannot run claude mcp login, authenticate through Claude Code's /mcp menu.

Start a session

Start an interactive session with the active organization and default model.

qbraid-code

Send one prompt and exit.

qbraid-code -p "explain this error"

Run qbraid-code --doctor to check the active profile.

List the qbraid-code commands without contacting qBraid or reading a profile.

qbraid-code --help

Run claude --help for arguments that qbraid-code forwards to Claude Code.

Switch organizations

List the installed organization profiles. The active profile has an asterisk.

qbraid-code --profiles

Use one organization for the next session only.

qbraid-code --profile research

Set the organization for future sessions.

qbraid-code --use-profile research

Run a setup check against a specific organization.

qbraid-code --profile research --doctor

Put --profile NAME first. The launcher removes both arguments before it starts Claude Code.

To replace an expired or revoked key, close sessions that use the profile. Then run this command:

qbraid-code --profile research --update-key

The command downloads the official installer and prompts for the replacement key. The installer verifies that the key belongs to the profile's organization. It stages a complete metadata generation, then switches current. If the update fails, the previous generation and key remain active.

Run the installer again when you need to update other profile settings.

Protect profile credentials

macOS stores keys in Keychain. Windows stores them in Credential Locker. Linux uses Secret Service through secret-tool when available. Headless Linux falls back to a private file with mode 0600.

Claude receives only a random per-launch loopback token. The status snapshot contains no API key.

A profile name belongs to one organization. If a key belongs to another organization, create a new profile. Running sessions stay bound to their original profile and generation.

Confirm the organization every time you resume a conversation.

qbraid-code --profile research --allow-profile-resume --resume SESSION_ID

The launcher excludes project and local Claude settings. This prevents a project hook from reading the session credential or replacing the gateway URL. The launcher still loads user settings.

Read the statusline

The statusline shows the organization that pays for the current session. Check this name before you continue work in a different organization.

qbraid-code ⎇ main │ Claude Opus 5 │ C13 █░░░░░ │ qBraid Research Lab · 4281 credits

A running session cannot switch organizations. Exit the session, then start a new one with --profile NAME.

The qBraid word uses the qBraid violet accent. Warning and low-credit colors keep their usual meaning. A local organization name includes (local) and a shortened verified organization ID.

qBraid Research Lab (local · org a1b2c3d4…) · 4281 credits

Credit snapshots show stale after five minutes without a successful launch refresh. A confirmed 401 or 403 response shows key expired until a key check succeeds or you rotate the key.

Choose a model

Choose the model when you start the session.

Use a GPT model

qbraid-code --model gpt-5.6-sol
qbraid-code --model gpt-5.4-mini -p "explain this error"

CLIProxyAPI runs on loopback only. Claude models pass through unchanged. GPT models use the gateway OpenAI-compatible surface. Each launch owns a random local bearer, runtime port, and proxy process. The proxy stops with the session. Its private runtime config is removed during launch cleanup.

GPT models accept at most 128 tools. Use --strict-mcp-config when many MCP servers would exceed that limit.

Model context limits

The installer stores exact model IDs and context limits in each profile's models.tsv. Verified built-in fallbacks cover Sol, Opus, Haiku, and the GPT-5.4 family. Unknown models stay at the conservative 200,000-token policy.

One-million-token models use Claude Code's [1m] model marker. Sol's 1,050,000-token window is advertised conservatively as 1,000,000 tokens. Other gateway models use CLAUDE_CODE_MAX_CONTEXT_TOKENS with their catalog value.

Choose the model when you start qbraid-code. To change models, exit and relaunch with --model. The launcher disables the in-session gateway picker because one process cannot use several context limits safely.

Model thinking

Claude Code sends adaptive thinking, display policy, and effort for current Opus models.

The older global thinking-disable workaround is gone. The 128-tool limit is independent of thinking.

Keep plain claude unchanged

The installer leaves plain claude untouched. Legacy qBraid gateway variables are removed from user settings during migration. --global is rejected because a project setting can replace the base URL and exfiltrate a reusable key.

How it works

Claude Code sends Anthropic Messages requests to the qBraid gateway. The local proxy translates only the GPT routes.

qbraid-code ── loopback CLIProxyAPI
                 ├─ Claude passthrough ── qBraid gateway
                 └─ GPT translation ──── qBraid gateway

Requests use qBraid credits at the usual rate. One hundred credits equal one US dollar.

Sign in to the qBraid MCP

The MCP endpoint uses OAuth rather than API keys. Sign in through your browser.

claude mcp login qbraid

Layout

Path	Purpose
~/.qbraid-code/.qbraid-code-install	Ownership marker for safe custom-root removal
~/.qbraid-code/active-profile	Future-session profile pointer
~/.qbraid-code/profiles/<name>/current	Atomic metadata-generation pointer
~/.qbraid-code/profiles/<name>/generations/*/env	URLs, model, secret reference, and proxy binary
~/.qbraid-code/profiles/<name>/generations/*/label*	Readable label and verified/local provenance
~/.qbraid-code/profiles/<name>/generations/*/models.tsv	Exact model context facts
~/.qbraid-code/secrets/*	Linux-only private key fallback
~/.qbraid-code/runtime.*	Short-lived proxy state
~/.qbraid-code/session.*	Short-lived non-secret status snapshot
~/.qbraid-code/profiles/<name>/generations/*/key-status	Confirmed local key-rejection marker
~/.qbraid-code/statusline.sh	Unix statusline adapter
~/.local/bin/qbraid-code	Unix launcher

Windows stores profile and runtime files under %USERPROFILE%\.qbraid-code. It installs the launcher under %USERPROFILE%\.local\bin.

Troubleshooting

Start with qbraid-code --doctor.

Rejected key. Create a key at account.qbraid.com/account/api-keys. Then close sessions that use the profile and run qbraid-code --profile NAME --update-key.

Wrong organization name. Reinstall that profile with QBRAID_CODE_PROFILE_LABEL set to a readable local name. API-key authentication does not always expose an authoritative organization name.

Local proxy unavailable. Re-run the installer for that profile. Every model uses one launch-owned loopback proxy.

Statusline missing. Add the printed statusLine entry to ~/.claude/settings.json. The Unix installer does not rewrite existing JSON without a real parser.

Uninstall

Close every qbraid-code session. Then remove qbraid-code from this device.

qbraid-code --uninstall

Type uninstall when prompted. For unattended local cleanup, use qbraid-code --uninstall --yes.

The command stops owned local proxies and removes every qbraid-code profile, stored local key, runtime file, proxy binary, statusline entry, qBraid MCP entry, and installed launcher. It preserves unrelated Claude settings and MCP servers. It tolerates files or credentials that are already missing.

Uninstall does not contact qBraid, Anthropic, or an OAuth service. It does not revoke API keys in your qBraid account. Revoke those keys separately at account.qbraid.com/account/api-keys.