diff --git a/litellm/proxy/client/cli/README.md b/litellm/proxy/client/cli/README.md index 1fdf8da7d2b..cf92dedbe98 100644 --- a/litellm/proxy/client/cli/README.md +++ b/litellm/proxy/client/cli/README.md @@ -492,7 +492,7 @@ lite codex exec "summarize the repo" Each command resolves your LiteLLM key (logging in via SSO when none is stored and you are at a terminal; otherwise it expects `LITELLM_PROXY_API_KEY` or `--api-key`), checks the key against the proxy so bad credentials fail immediately instead of deep inside the agent, exports the environment variables the agent reads, then replaces itself with the agent process. -The right variables are picked per agent. Claude Code gets `ANTHROPIC_BASE_URL` (the proxy root, so it appends `/v1/messages`) and `ANTHROPIC_AUTH_TOKEN`, with any stray `ANTHROPIC_API_KEY` cleared so the proxy token wins, and `ENABLE_TOOL_SEARCH=true` (unless you already set it) so Claude Code keeps tool search on even though the base URL is a proxy rather than a first-party Anthropic host. It also gets `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` (again unless you already set it) so Claude Code v2.1.129+ fills its `/model` picker from the proxy's `/v1/models`; Claude Code only lists entries whose id contains `claude` or `anthropic`, so the proxy lists every other group to Claude Code as `claude-router-` and marks a group whose input window reaches 1M with `[1m]`, and a request on such an id is served by the group. Older Claude Code versions ignore the variable. Export it as `0` to turn discovery off. Codex and OpenCode get `OPENAI_BASE_URL` (the proxy plus `/v1`) and `OPENAI_API_KEY`. Codex ignores `OPENAI_BASE_URL`, so it is additionally pointed at the proxy through a custom provider passed as `-c` config overrides (HTTP/SSE Responses transport, since the proxy does not speak the Responses WebSocket protocol). OpenCode additionally gets `OPENCODE_CONFIG_CONTENT` holding a generated `litellm` provider (`@ai-sdk/openai-compatible`, the proxy `/v1` URL, `{env:OPENAI_API_KEY}`) with one model entry per chat model your key can see on `/v1/models`, so its model picker mirrors the proxy without a hand-maintained `opencode.json`; OpenCode merges that over your own config files, and if you already export `OPENCODE_CONFIG_CONTENT` yours is left alone. When the list cannot be fetched, `lite opencode` says so on stderr and launches anyway. Codex gets the same list as a catalog file, `$CODEX_HOME/litellm-models.json` (default `~/.codex/`), passed as `-c model_catalog_json=` so `/model` lists exactly the proxy's chat models; a proxy model the installed Codex already knows (`gpt-5.5`, say) keeps that Codex's own entry, reasoning levels and prompt included, and only its place in the picker comes from the proxy, while a model Codex does not know gets the plain entry Codex uses for an unknown `-m` slug, plus whichever reasoning levels its model group lists on `/model_group/info` the installed Codex can parse. Before launching, `lite codex` asks the installed Codex for its own list and then has it read the written file back (both through `codex debug models`), and when the fetch, either of those or the write fails (Codex releases older than 0.130 have no such command) it says so on stderr and launches with Codex's built-in catalog, leaving a rejected file in place. +The right variables are picked per agent. Claude Code gets `ANTHROPIC_BASE_URL` (the proxy root, so it appends `/v1/messages`) and `ANTHROPIC_AUTH_TOKEN`, with any stray `ANTHROPIC_API_KEY` cleared so the proxy token wins (when the `apiKeyHelper` Claude Code would load is the one `lite login --pkce --config-claude` wrote for this proxy, `ANTHROPIC_AUTH_TOKEN` is left out instead, so that helper keeps renewing the key for as long as the session runs), and `ENABLE_TOOL_SEARCH=true` (unless you already set it) so Claude Code keeps tool search on even though the base URL is a proxy rather than a first-party Anthropic host. It also gets `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` (again unless you already set it) so Claude Code v2.1.129+ fills its `/model` picker from the proxy's `/v1/models`; Claude Code only lists entries whose id contains `claude` or `anthropic`, so the proxy lists every other group to Claude Code as `claude-router-` and marks a group whose input window reaches 1M with `[1m]`, and a request on such an id is served by the group. Older Claude Code versions ignore the variable. Export it as `0` to turn discovery off. Codex and OpenCode get `OPENAI_BASE_URL` (the proxy plus `/v1`) and `OPENAI_API_KEY`. Codex ignores `OPENAI_BASE_URL`, so it is additionally pointed at the proxy through a custom provider passed as `-c` config overrides (HTTP/SSE Responses transport, since the proxy does not speak the Responses WebSocket protocol). OpenCode additionally gets `OPENCODE_CONFIG_CONTENT` holding a generated `litellm` provider (`@ai-sdk/openai-compatible`, the proxy `/v1` URL, `{env:OPENAI_API_KEY}`) with one model entry per chat model your key can see on `/v1/models`, so its model picker mirrors the proxy without a hand-maintained `opencode.json`; OpenCode merges that over your own config files, and if you already export `OPENCODE_CONFIG_CONTENT` yours is left alone. When the list cannot be fetched, `lite opencode` says so on stderr and launches anyway. Codex gets the same list as a catalog file, `$CODEX_HOME/litellm-models.json` (default `~/.codex/`), passed as `-c model_catalog_json=` so `/model` lists exactly the proxy's chat models; a proxy model the installed Codex already knows (`gpt-5.5`, say) keeps that Codex's own entry, reasoning levels and prompt included, and only its place in the picker comes from the proxy, while a model Codex does not know gets the plain entry Codex uses for an unknown `-m` slug, plus whichever reasoning levels its model group lists on `/model_group/info` the installed Codex can parse. Before launching, `lite codex` asks the installed Codex for its own list and then has it read the written file back (both through `codex debug models`), and when the fetch, either of those or the write fails (Codex releases older than 0.130 have no such command) it says so on stderr and launches with Codex's built-in catalog, leaving a rejected file in place. pi ignores base-URL environment variables entirely, so `lite pi` (kept out of the `lite --help` command listing for now, but fully functional) wires it up differently: before handoff it fetches the models your key can use from the proxy's `/v1/models` (plus each model's context window and output cap from `/model_group/info`, when available) and syncs them into a `litellm` provider entry in pi's `~/.pi/agent/models.json` (honoring `PI_CODING_AGENT_DIR`), then starts pi on that provider's first model via an injected `--model litellm/`. Only that one provider entry is rewritten; the rest of the file, including any other custom providers, is left alone. The entry references the key as `$LITELLM_PROXY_API_KEY`, which the wrapper exports for the session, so the token itself never lands on disk and plain `pi` outside the wrapper simply shows the litellm models as unavailable. The entry also turns on pi's session header (`x-session-id`, sent by pi 0.80.7 and later), so every chat turn of one pi session shares one session id in the logs and sticks to one deployment when session affinity is on. A custom `pi --session-id` must be at least 8 letters, digits, `_`, or `-` for the proxy to read it. Your own flags come after the injected pin, so `lite pi --model litellm/` wins, and inside the TUI the `/model` picker lists every synced litellm model. @@ -506,7 +506,7 @@ To pin the model, pass the agent's own model flag (for example `lite claude --mo The token minted by `lite login` is a short-lived, per-session agent credential, not a managed virtual key. It is scoped to the user and team you authenticated as, inherits that user's and team's models and budgets, and is enforced on the proxy exactly like a virtual key on the same team (guardrails, routing, logging, spend). Spend is tracked against the shared team and user budgets, so running several agents (or logging in more than once) does not hand each session its own separate budget; they all draw down the same team/user allowance. There is no separate per-session cap, so sustained agent use is not capped at a small chat-session limit. -The credential is short-lived by design (default 24h, configurable via `LITELLM_CLI_JWT_EXPIRATION_HOURS`); run `lite login` again to refresh it, which also re-reads your latest team and user settings. It does not appear in the Keys UI and cannot be rotated or revoked mid-session. `lite auth print-token` (usable as Claude Code's `apiKeyHelper`) prints it without asking the proxy for its first 24 hours, or `LITELLM_CLI_JWT_EXPIRATION_HOURS` if you set it on the client. After that, `print-token` and `lite whoami` ask the proxy whether it still accepts the token, and `print-token` fails once the proxy rejects it. There is no silent renewal, so a long-running session needs a fresh `lite login` each time the proxy's token lifetime runs out. If the proxy's tokens last less than 24 hours, set the same `LITELLM_CLI_JWT_EXPIRATION_HOURS` on the client so `print-token` stops printing the token once it runs out. `lite up` still starts a new login once the token is older than that same client window. It copies the token into Claude Code's settings as a static key that it never renews, so a fresh login gives Claude Code the proxy's full token lifetime instead of whatever an old token has left. `lite claude`, `lite codex`, `lite opencode`, and `lite pi` work with it on a default deployment; `EXPERIMENTAL_UI_LOGIN` is not required. `lite login --pkce` is the exception to the re-login: it signs in through your system browser with OAuth authorization code and PKCE and stores a refresh token next to the key, so every `lite` command and `lite auth print-token` renew the key on their own shortly before it expires, `lite whoami` shows when the current key expires, and `lite logout` revokes the refresh token on the proxy (it needs a proxy that serves `/.well-known/litellm-cli-auth`; see [Browser sign-in with PKCE](https://docs.litellm.ai/docs/proxy/cli_sso#browser-sign-in-with-pkce)). When a renewal is refused, for example after a `lite logout` run from another copy of the credential, the command prints why on stderr and, once the key has run out, tells you to run `lite login --pkce` again. Only the holder can end a `--pkce` session early, with `lite logout`; an admin has no button for it, but every renewal re-reads the user on the proxy, so deactivating the user or removing them from the team makes the next renewal fail and the key runs out within `LITELLM_CLI_JWT_EXPIRATION_HOURS`. On a proxy with more than one worker or replica, configure Redis (`litellm_settings.cache` with Redis `cache_params`, or `general_settings.coordination_redis`) so a refresh token stays single-use and `lite logout` holds on every worker; without Redis each worker keeps its own record. If you need a long-lived, rotatable key that shows up in the Keys UI, create a dedicated virtual key in the dashboard and pass it via `--api-key` or `LITELLM_PROXY_API_KEY` instead. +The credential is short-lived by design (default 24h, configurable via `LITELLM_CLI_JWT_EXPIRATION_HOURS`); run `lite login` again to refresh it, which also re-reads your latest team and user settings. It does not appear in the Keys UI and cannot be rotated or revoked mid-session. `lite auth print-token` (usable as Claude Code's `apiKeyHelper`) prints it without asking the proxy for its first 24 hours, or `LITELLM_CLI_JWT_EXPIRATION_HOURS` if you set it on the client. After that, `print-token` and `lite whoami` ask the proxy whether it still accepts the token, and `print-token` fails once the proxy rejects it. There is no silent renewal, so a long-running session needs a fresh `lite login` each time the proxy's token lifetime runs out. If the proxy's tokens last less than 24 hours, set the same `LITELLM_CLI_JWT_EXPIRATION_HOURS` on the client so `print-token` stops printing the token once it runs out. `lite up` still starts a new login once the token is older than that same client window. It copies the token into Claude Code's settings as a static key that it never renews, so a fresh login gives Claude Code the proxy's full token lifetime instead of whatever an old token has left. `lite claude`, `lite codex`, `lite opencode`, and `lite pi` work with it on a default deployment; `EXPERIMENTAL_UI_LOGIN` is not required. `lite login --pkce` is the exception to the re-login: it signs in through your system browser with OAuth authorization code and PKCE and stores a refresh token next to the key, so every `lite` command and `lite auth print-token` renew the key on their own shortly before it expires (with `--config-claude`, Claude Code runs `lite auth print-token` itself, so its key renews too), `lite whoami` shows when the current key expires, and `lite logout` revokes the refresh token on the proxy (it needs a proxy that serves `/.well-known/litellm-cli-auth`; see [Browser sign-in with PKCE](https://docs.litellm.ai/docs/proxy/cli_sso#browser-sign-in-with-pkce)). When a renewal is refused, for example after a `lite logout` run from another copy of the credential, the command prints why on stderr and, once the key has run out, tells you to run `lite login --pkce` again. Only the holder can end a `--pkce` session early, with `lite logout`; an admin has no button for it, but every renewal re-reads the user on the proxy, so deactivating the user or removing them from the team makes the next renewal fail and the key runs out within `LITELLM_CLI_JWT_EXPIRATION_HOURS`. On a proxy with more than one worker or replica, configure Redis (`litellm_settings.cache` with Redis `cache_params`, or `general_settings.coordination_redis`) so a refresh token stays single-use and `lite logout` holds on every worker; without Redis each worker keeps its own record. If you need a long-lived, rotatable key that shows up in the Keys UI, create a dedicated virtual key in the dashboard and pass it via `--api-key` or `LITELLM_PROXY_API_KEY` instead. ### Route Every Claude Code Session Through the Proxy @@ -536,7 +536,7 @@ lite --base-url https://your-proxy.example.com login --config-claude It writes the same settings `lite up` does, `env.ANTHROPIC_BASE_URL`, `env.ENABLE_TOOL_SEARCH`, `env.CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`, and the key this login minted as `env.ANTHROPIC_AUTH_TOKEN`, but persistently: no foreground process to keep alive, and `lite unconfigure claude` restores what it changed (see below). Every other key in `~/.claude/settings.json` is preserved, the file is created if it does not exist, and it is written atomically with owner-only permissions. Plain `lite login` is unchanged; nothing happens to your Claude Code config unless you pass the flag -The key in the file is the login's own, so it expires with it (24h by default): run `lite login --config-claude` again after that, which rewrites the key in place. Earlier versions wrote an `apiKeyHelper` that ran `lite auth print-token` instead, so a later login refreshed Claude Code by itself; that meant Claude Code spawning a full `lite` start, keychain check included, on every credential refresh, so the helper is no longer written and a stale one is stripped by the next `--config-claude` or `configure claude`. Like `lite up`, the flag refuses to run while a `lite up` session holds a backup, and tells you to run `lite down` first +After a plain `lite login`, the key in the file is the login's own, so it expires with it (24h by default): run `lite login --config-claude` again after that, which rewrites the key in place. A `lite login --pkce --config-claude` writes an `apiKeyHelper` that runs `lite auth print-token` instead of the key. Claude Code runs it at startup and again once the key it got is five minutes old, and `print-token` renews the key from the stored refresh token before it expires, so Claude Code keeps working across days and asks for a browser sign-in only once the refresh token goes unused for 14 days. Each run is a full `lite` start, which takes a second or two. The helper names the `lite` found on your `PATH` by its absolute path, so when `lite` is not on `PATH`, or the login could not be saved for later commands, the key is written as for a plain login and the command says why. The status line cannot run the helper, so in this mode it shows the routed model from the transcript but not the session's cost bars. A later plain `--config-claude` or `configure claude` replaces the helper with a static key. Like `lite up`, the flag refuses to run while a `lite up` session holds a backup, and tells you to run `lite down` first #### Configuring Claude Code or Codex Once, With a Virtual Key diff --git a/litellm/proxy/client/cli/commands/agents.py b/litellm/proxy/client/cli/commands/agents.py index 12d97ef6cce..daf2e2a4951 100644 --- a/litellm/proxy/client/cli/commands/agents.py +++ b/litellm/proxy/client/cli/commands/agents.py @@ -29,10 +29,12 @@ from litellm.types.llms.base_model import LiteLLMBaseModel from .auth import cli_context_obj, context_secret_vault, get_stored_api_key, login from .claude_settings import ( + API_KEY_HELPER_KEY, ENV_KEY, ClaudeSettingsError, claude_settings_path, install_statusline_script, + lite_api_key_helper, load_json_or_empty, ) from .cmd_quoting import quote_for_cmd @@ -130,6 +132,7 @@ def build_agent_env( profiles: frozenset[str], *, subscription: bool = False, + helper_renews_key: bool = False, ) -> dict[str, str]: """Return a copy of base_env wired to route the agent through the proxy. @@ -148,6 +151,8 @@ def build_agent_env( travels in the x-litellm-api-key header through ANTHROPIC_CUSTOM_HEADERS, and no ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY is left in the environment, since either one makes Claude Code stop using the subscription (and its connectors). + With helper_renews_key=True the Anthropic profile leaves ANTHROPIC_AUTH_TOKEN out, so Claude Code takes + its key from the renewing apiKeyHelper in its settings instead of a launch-time copy that expires. With subscription=True the OpenAI profile keeps Codex on its ChatGPT login: the key goes to LITELLM_PROXY_API_KEY, which Codex sends in the x-litellm-api-key header, and OPENAI_API_KEY and OPENAI_BASE_URL are left exactly as the caller had them, so the key is never offered to Codex as an @@ -162,6 +167,8 @@ def build_agent_env( env.get(ANTHROPIC_CUSTOM_HEADERS_ENV, ""), api_key ) env.pop(ANTHROPIC_AUTH_TOKEN_ENV, None) + elif helper_renews_key: + env.pop(ANTHROPIC_AUTH_TOKEN_ENV, None) else: env[ANTHROPIC_AUTH_TOKEN_ENV] = api_key env.pop(ANTHROPIC_API_KEY_ENV, None) @@ -246,7 +253,7 @@ def _settings_json(base: Mapping[str, JsonValue], api_key: str, inherited_header own_headers if isinstance(own_headers, str) else inherited_headers, api_key ) overlay: Final = {**base_env, **_SUBSCRIPTION_SETTINGS_ENV, ANTHROPIC_CUSTOM_HEADERS_ENV: headers} - return json.dumps({**base, ENV_KEY: overlay}, separators=(",", ":")) + return json.dumps({**base, API_KEY_HELPER_KEY: "", ENV_KEY: overlay}, separators=(",", ":")) def _inherited_custom_headers(settings_files: Sequence[Mapping[str, JsonValue]], environ: Mapping[str, str]) -> str: @@ -274,6 +281,29 @@ def claude_settings_files( raise AgentRunError(str(e)) from e +def lite_helper_renews_key( + base_url: str, settings_files: Sequence[Mapping[str, JsonValue]], which: Callable[[str], str | None] +) -> bool: + """Whether the apiKeyHelper Claude Code will run, the first one in settings precedence, is the one + `lite login --pkce --config-claude` wrote for this proxy. Claude Code prefers ANTHROPIC_AUTH_TOKEN over a + helper and warns when both are set, so exporting the key too would pin a copy that expires mid-session.""" + configured: Final = next( + (settings[API_KEY_HELPER_KEY] for settings in settings_files if API_KEY_HELPER_KEY in settings), None + ) + helper: Final = lite_api_key_helper(base_url, which=which) + return helper is not None and configured == helper.command + + +def _readable_settings_files( + read_settings: Callable[[Path], Mapping[str, JsonValue]], environ: Mapping[str, str], project_dir: Path +) -> tuple[Mapping[str, JsonValue], ...]: + """A launch that only checks for lite's helper goes ahead on a malformed settings file, as it did before.""" + try: + return claude_settings_files(read_settings, environ, project_dir) + except AgentRunError: + return () + + OVERLAY_FILE_NAME: Final = "litellm-subscription-overlay.json" @@ -303,11 +333,12 @@ def subscription_launch_args( Claude Code applies `env` from its settings files over the process environment, so a key that `lite up` or `lite configure claude` left in ANTHROPIC_AUTH_TOKEN would land back in `Authorization`, and an - ANTHROPIC_CUSTOM_HEADERS there would drop the x-litellm-api-key header. The overlay blanks both credential - keys (read as unset for this session only) and carries the custom headers with the LiteLLM key appended, - taking the headers from the user's `--settings`, else the settings files in Claude Code's precedence order, - else the process environment. Any `--settings` the user passed is stripped and the last one (inline JSON or a - file, the one Claude Code would keep) is merged in, since Claude Code keeps only the last `--settings`. + ANTHROPIC_CUSTOM_HEADERS there would drop the x-litellm-api-key header, and an apiKeyHelper outranks the + claude.ai login. The overlay blanks both credential keys and the helper (read as unset for this session only) + and carries the custom headers with the LiteLLM key appended, taking the headers from the user's + `--settings`, else the settings files in Claude Code's precedence order, else the process environment. Any + `--settings` the user passed is stripped and the last one (inline JSON or a file, the one Claude Code would + keep) is merged in, since Claude Code keeps only the last `--settings`. """ inherited: Final = _inherited_custom_headers(settings_files, environ) user_value, rest = _split_settings_flags(tuple(command[1:])) @@ -1122,6 +1153,12 @@ def run_agent( (verify_subscription if subscription else verify)(base_url, api_key) env_before_sync: Final = base_env if base_env is not None else os.environ + project: Final = project_dir if project_dir is not None else Path.cwd() + helper_renews_key: Final = ( + not subscription + and PROFILE_ANTHROPIC in profiles + and lite_helper_renews_key(base_url, _readable_settings_files(read_settings, env_before_sync, project), which) + ) synced: Final = ( _NO_EXTRA_ENV if subscription else sync_models(binary, env_before_sync, base_url, api_key, skip_verify) ) @@ -1133,7 +1170,14 @@ def run_agent( env: Final = MappingProxyType( { - **build_agent_env(env_before_sync, base_url, api_key, profiles, subscription=subscription), + **build_agent_env( + env_before_sync, + base_url, + api_key, + profiles, + subscription=subscription, + helper_renews_key=helper_renews_key, + ), **(synced if isinstance(synced, Mapping) else _NO_EXTRA_ENV), } ) @@ -1148,9 +1192,7 @@ def run_agent( command, api_key, env_before_sync, - claude_settings_files( - read_settings, env_before_sync, project_dir if project_dir is not None else Path.cwd() - ), + claude_settings_files(read_settings, env_before_sync, project), write_overlay, ) if subscription and os.path.basename(command[0]) == "claude" diff --git a/litellm/proxy/client/cli/commands/auth.py b/litellm/proxy/client/cli/commands/auth.py index e38f54adc4f..d02682f7149 100644 --- a/litellm/proxy/client/cli/commands/auth.py +++ b/litellm/proxy/client/cli/commands/auth.py @@ -42,12 +42,15 @@ from litellm.litellm_core_utils.cli_token_utils import ( from .claude_settings import ( STARTING_MODEL_ROLE, + ApiKeyHelper, + ClaudeCredential, ClaudeSettingsError, KeepModel, StaticToken, claude_settings_path, configure_claude_settings, configure_state_path, + lite_api_key_helper, refuse_while_owned, settings_file_owners, ) @@ -807,16 +810,26 @@ def _render_and_prompt_for_team_selection(teams: list[CliTeam]) -> str | None: return None -def _configure_claude_code(base_url: str, api_key: str) -> None: - """Write the key this login just minted into Claude Code's settings.json as a static token, undoable with - `lite unconfigure claude`. The key expires with the login, so the flag is the re-wire step of each login - rather than a one-time setup: no apiKeyHelper is written, since Claude Code would spawn `lite` (and its - keychain probe) on every credential refresh to keep one fresh.""" +def _claude_credential(base_url: str, api_key: str, renews: bool, stored: SecretSave) -> ClaudeCredential: + """A helper only for a key `lite` can renew and kept: `print-token` renews from the stored record, so a + login the store refused, or one with no refresh token, gets the minted key as a static token.""" + if not renews or isinstance(stored, (CredentialNotSaved, CredentialNotRecorded)): + return StaticToken(api_key) + helper: Final = lite_api_key_helper(base_url) + if helper is None: + click.echo("`lite` is not on your PATH, so Claude Code cannot run it to renew this login's key.") + return StaticToken(api_key) + return helper + + +def _configure_claude_code(base_url: str, credential: ClaudeCredential, renews: bool) -> None: + """Wire Claude Code's settings.json to this login, undoable with `lite unconfigure claude`. A static key + expires with the login, so the flag is then the re-wire step of each login; a helper renews in place.""" settings_path: Final = claude_settings_path(os.environ) try: configure_claude_settings( base_url, - StaticToken(api_key), + credential, KeepModel(), settings_path, configure_state_path(settings_path), @@ -825,14 +838,27 @@ def _configure_claude_code(base_url: str, api_key: str) -> None: except ClaudeSettingsError as e: raise click.ClickException(f"Logged in, but could not configure Claude Code: {e}") click.echo(f"\nConfigured Claude Code: {settings_path} now routes through {base_url.rstrip('/')}.") + match credential: + case ApiKeyHelper(): + click.echo( + "Claude Code gets this login's key from `lite auth print-token`, which renews it before it expires." + ) + case StaticToken(): + click.echo( + f"This login's key is stored in the file, so run `{_login_command(renews)} --config-claude` again " + "after it expires." + ) + if not renews: + click.echo("`lite login --pkce --config-claude` instead lets Claude Code renew the key on its own.") + case _: + assert_never(credential) click.echo( - "This login's key is stored in the file, so run `lite login --config-claude` again after it expires. " "Your other Claude Code settings were left untouched. Restart Claude Code to pick this up. " f"Undo with `lite unconfigure claude`; `lite configure claude --model` sets {STARTING_MODEL_ROLE}." ) -def _finish_login(base_url: str, api_key: str, config_claude: bool, stored: SecretSave) -> None: +def _finish_login(base_url: str, api_key: str, config_claude: bool, stored: SecretSave, *, renews: bool) -> None: """Claude Code is configured from the key in hand, so it does not wait on the CLI's own store: a login whose token file or keychain refused it still has a usable key, and `--config-claude` asked for exactly that key to be written into settings.json.""" @@ -842,7 +868,7 @@ def _finish_login(base_url: str, api_key: str, config_claude: bool, stored: Secr click.echo(f"JWT Token: {api_key[:20]}...") click.echo(storage_notice(stored)) if config_claude: - _configure_claude_code(base_url, api_key) + _configure_claude_code(base_url, _claude_credential(base_url, api_key, renews, stored), renews) if isinstance(stored, (CredentialNotSaved, CredentialNotRecorded)): if config_claude: click.echo("Claude Code was configured with this key even though the CLI itself could not keep it.") @@ -873,7 +899,7 @@ def _pkce_login(base_url: str, config_claude: bool, vault: SecretVault) -> None: click.echo(f"Authentication failed: {credential.reason}") return stored: Final = _replace_stored_token(pkce_token_record(base_url, credential), http, vault) - _finish_login(base_url, credential.access_token, config_claude, stored) + _finish_login(base_url, credential.access_token, config_claude, stored, renews=True) @click.command(name="login") @@ -882,8 +908,9 @@ def _pkce_login(base_url: str, config_claude: bool, vault: SecretVault) -> None: is_flag=True, default=False, help=( - "After logging in, write this login's key into ~/.claude/settings.json so Claude Code routes through " - "this proxy; run it again after the key expires. Unrelated settings are preserved." + "After logging in, wire ~/.claude/settings.json so Claude Code routes through this proxy. A --pkce login " + "gets an apiKeyHelper that renews the key; any other login writes the key itself, so run it again after " + "the key expires. Unrelated settings are preserved." ), ) @click.option( @@ -965,7 +992,7 @@ def login(ctx: click.Context, config_claude: bool, pkce: bool | None) -> None: context_secret_vault(ctx), ) - _finish_login(base_url, api_key, config_claude, stored) + _finish_login(base_url, api_key, config_claude, stored, renews=False) return else: click.echo("Authentication timed out. Please try again.") diff --git a/litellm/proxy/client/cli/commands/claude_settings.py b/litellm/proxy/client/cli/commands/claude_settings.py index 60492a81cab..46388405aad 100644 --- a/litellm/proxy/client/cli/commands/claude_settings.py +++ b/litellm/proxy/client/cli/commands/claude_settings.py @@ -3,16 +3,17 @@ `lite up` and `lite autoroute start` patch this file temporarily and restore it on exit; `lite configure claude` patches it persistently and records how to undo it. All of them need the same merge, and `up` already imports from `auth`, so the -shared parts live here rather than in any one command module. The credential is -always a static token in `env.ANTHROPIC_AUTH_TOKEN`: Claude Code's `apiKeyHelper` -would spawn a `lite` process on every credential refresh, and that process touches -the keychain, so nothing here writes one; a helper left by an earlier version is -owned like any other key and stripped. +shared parts live here rather than in any one command module. The credential is a +static token in `env.ANTHROPIC_AUTH_TOKEN`, except for a login `lite` renews on its own, +which gets an `apiKeyHelper` running `lite auth print-token`: Claude Code reruns it +every few minutes, so the key it sends follows each renewal. A helper is owned like +any other key, so writing one credential strips the other. """ import hashlib import json import shlex +import shutil import sys from collections.abc import Callable, Mapping, Sequence from dataclasses import dataclass @@ -138,6 +139,16 @@ class StaticToken: token: str +@dataclass(frozen=True, slots=True) +class ApiKeyHelper: + """A `lite auth print-token` command Claude Code reruns for a fresh key, written into the top-level apiKeyHelper.""" + + command: str + + +ClaudeCredential: TypeAlias = StaticToken | ApiKeyHelper + + @dataclass(frozen=True, slots=True) class KeepModel: """Leave the top-level `model` as it is, the user's or an earlier configure's (a re-login).""" @@ -305,6 +316,24 @@ def _land( raise ClaudeSettingsError(f"Could not {'remove' if staged is None else 'write'} {path}: {e}") from e +def lite_api_key_helper( + base_url: str, platform: str = sys.platform, which: Callable[[str], str | None] = shutil.which +) -> ApiKeyHelper | None: + """The helper for a renewing login, or None when `lite` is not on PATH to be run by absolute path. + + Claude Code hands the string to `sh` on POSIX and cmd.exe on Windows, so every token is quoted for + that shell. `--base-url` makes `print-token` refuse a key a later `lite login` minted for another + proxy, and it belongs to the top-level group, so it goes before the subcommand. + """ + lite_path: Final = which("lite") + if lite_path is None: + return None + quote: Final = quote_for_cmd if platform.startswith("win") else shlex.quote + return ApiKeyHelper( + " ".join(quote(token) for token in (lite_path, "--base-url", base_url.rstrip("/"), "auth", "print-token")) + ) + + def statusline_command(script_path: Path, platform: str = sys.platform) -> str: """This interpreter, not a bare `python3`: it is the one the apiKeyHelper already depends on.""" quote: Final = quote_for_cmd if platform.startswith("win") else shlex.quote @@ -378,7 +407,7 @@ def with_status_line(settings: Mapping[str, JsonValue], command: str) -> Mapping def merge_claude_settings( settings: Mapping[str, JsonValue], base_url: str, - credential: StaticToken, + credential: ClaudeCredential, default_model: str | None = None, tier_model: str | None = None, *, @@ -386,8 +415,9 @@ def merge_claude_settings( ) -> Mapping[str, JsonValue]: """Return a new settings mapping wired to route Claude Code through the proxy. - The token lands in env.ANTHROPIC_AUTH_TOKEN; the other credential slots (a stray ANTHROPIC_API_KEY, - an apiKeyHelper) are removed, since Claude Code given two credentials may send the wrong one. + A StaticToken lands in env.ANTHROPIC_AUTH_TOKEN, an ApiKeyHelper in the top-level apiKeyHelper; the + other credential slots are removed either way, since Claude Code given two credentials may send the + wrong one, and ANTHROPIC_AUTH_TOKEN would win over the helper. ENABLE_TOOL_SEARCH and CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY get their defaults only when missing. `default_model` is the top-level `model` and env.ANTHROPIC_MODEL (see StartOn); `tier_model` is `lite autoroute start`'s knob that points every ANTHROPIC_DEFAULT_*_MODEL at one @@ -402,7 +432,8 @@ def merge_claude_settings( (ENABLE_GATEWAY_MODEL_DISCOVERY_KEY, ENABLE_GATEWAY_MODEL_DISCOVERY_VALUE), ), ((key, value) for key, value in current_env.items() if key not in _CREDENTIAL_ENV_KEYS), - ((ANTHROPIC_BASE_URL_KEY, base_url.rstrip("/")), (ANTHROPIC_AUTH_TOKEN_KEY, credential.token)), + ((ANTHROPIC_BASE_URL_KEY, base_url.rstrip("/")),), + ((ANTHROPIC_AUTH_TOKEN_KEY, credential.token),) if isinstance(credential, StaticToken) else (), ((ANTHROPIC_MODEL_KEY, default_model),) if default_model is not None else (), ((key, tier_model) for key in ANTHROPIC_DEFAULT_MODEL_ENV_KEYS if tier_model is not None), ) @@ -415,6 +446,7 @@ def merge_claude_settings( if key not in (API_KEY_HELPER_KEY, ENV_KEY) ), ((ENV_KEY, env),), + ((API_KEY_HELPER_KEY, credential.command),) if isinstance(credential, ApiKeyHelper) else (), ((MODEL_KEY, default_model),) if default_model is not None else (), ) ) @@ -520,7 +552,7 @@ def preflight_claude_settings(settings_path: Path) -> None: def configure_claude_settings( base_url: str, - credential: StaticToken, + credential: ClaudeCredential, model: ModelChoice, settings_path: Path, state_path: Path, @@ -671,6 +703,8 @@ __all__ = ( "STARTING_MODEL_ROLE", "STATUSLINE_SCRIPT_PATH", "STATUS_LINE_KEY", + "ApiKeyHelper", + "ClaudeCredential", "ClaudeSettingsError", "ConfigureReceipt", "KeepModel", @@ -685,6 +719,7 @@ __all__ = ( "claude_settings_path", "configure_claude_settings", "configure_state_path", + "lite_api_key_helper", "load_json_or_empty", "merge_claude_settings", "read_configure_receipt", diff --git a/tests/unit/proxy/client/cli/test_agents.py b/tests/unit/proxy/client/cli/test_agents.py index 60a19b11d72..dddd4ba3b9f 100644 --- a/tests/unit/proxy/client/cli/test_agents.py +++ b/tests/unit/proxy/client/cli/test_agents.py @@ -217,6 +217,9 @@ class _FakeJsonResponse: return self._payload +LITE_HELPER: Final = "/usr/local/bin/lite --base-url http://localhost:4000 auth print-token" + + def _overlay_writer(tmp_path): def write(text, environ): target = tmp_path / "overlay.json" @@ -1666,6 +1669,57 @@ class TestRunAgent: ) assert calls["args"] == ("claude", "--resume") + @pytest.mark.parametrize( + ("project_local", "user", "exports_the_key"), + [ + ({}, {"apiKeyHelper": LITE_HELPER}, False), + ({}, {"apiKeyHelper": LITE_HELPER.replace("localhost:4000", "other-proxy:4000")}, True), + ({}, {"apiKeyHelper": "/opt/mine/helper"}, True), + ({"apiKeyHelper": "/opt/mine/helper"}, {"apiKeyHelper": LITE_HELPER}, True), + ({}, {}, True), + ], + ids=["lites-helper-for-this-proxy", "another-proxy", "users-own-helper", "project-helper-wins", "no-helper"], + ) + def test_claude_takes_the_key_from_lites_renewing_helper_only_when_it_is_the_one_claude_code_runs( + self, tmp_path, project_local, user, exports_the_key + ): + files = { + tmp_path / "repo" / ".claude" / "settings.local.json": project_local, + tmp_path / "cfg" / "settings.json": user, + } + launched = {} + run_agent( + "http://localhost:4000", + "sk-key", + ["claude"], + base_env={"CLAUDE_CONFIG_DIR": str(tmp_path / "cfg"), "ANTHROPIC_AUTH_TOKEN": "sk-stale"}, + which=lambda name: f"/usr/local/bin/{name}", + verify=lambda *a: None, + launcher=lambda p, a, e: launched.update(env=dict(e)), + read_settings=lambda path: files.get(path, {}), + project_dir=tmp_path / "repo", + ) + assert launched["env"]["ANTHROPIC_BASE_URL"] == "http://localhost:4000" + assert launched["env"].get("ANTHROPIC_AUTH_TOKEN") == ("sk-key" if exports_the_key else None) + + def test_a_malformed_settings_file_still_launches_claude_with_the_key(self, tmp_path): + def unreadable(path): + raise ClaudeSettingsError(f"{path} contains invalid JSON") + + launched = {} + run_agent( + "http://localhost:4000", + "sk-key", + ["claude"], + base_env={"CLAUDE_CONFIG_DIR": str(tmp_path / "cfg")}, + which=lambda name: f"/usr/local/bin/{name}", + verify=lambda *a: None, + launcher=lambda p, a, e: launched.update(env=dict(e)), + read_settings=unreadable, + project_dir=tmp_path / "repo", + ) + assert launched["env"]["ANTHROPIC_AUTH_TOKEN"] == "sk-key" + def test_missing_binary_raises_with_install_hint(self): with pytest.raises(AgentRunError, match=r"claude.*Install it first"): run_agent( @@ -1754,7 +1808,9 @@ class TestRunAgent: assert launched["env"]["ANTHROPIC_CUSTOM_HEADERS"] == "x-litellm-api-key: Bearer sk-key" assert "ANTHROPIC_AUTH_TOKEN" not in launched["env"] - def test_subscription_launch_blanks_the_credentials_claude_code_would_load_from_settings_json(self, tmp_path): + def test_subscription_launch_blanks_the_credentials_and_helper_claude_code_would_load_from_settings( + self, tmp_path + ): launched = {} run_agent( "http://localhost:4000", @@ -1770,11 +1826,12 @@ class TestRunAgent: ) assert launched["args"][:2] == ("claude", "--settings") assert _overlay(launched["args"]) == { + "apiKeyHelper": "", "env": { "ANTHROPIC_AUTH_TOKEN": "", "ANTHROPIC_API_KEY": "", "ANTHROPIC_CUSTOM_HEADERS": "x-litellm-api-key: Bearer sk-key", - } + }, } assert launched["args"][3:] == ("--resume",) @@ -1880,6 +1937,7 @@ class TestRunAgent: assert launched["args"][:2] == ["claude", "--settings"] assert _overlay(launched["args"]) == { "model": "opus", + "apiKeyHelper": "", "env": { "ANTHROPIC_AUTH_TOKEN": "", "FOO": "bar", @@ -1906,6 +1964,7 @@ class TestRunAgent: assert launched["args"][:2] == ["claude", "--settings"] assert _overlay(launched["args"]) == { "theme": "dark", + "apiKeyHelper": "", "env": { "ANTHROPIC_API_KEY": "", "ANTHROPIC_AUTH_TOKEN": "", @@ -1984,6 +2043,7 @@ class TestRunAgent: assert launched["args"][:2] == ["claude", "--settings"] assert _overlay(launched["args"]) == { "theme": "dark", + "apiKeyHelper": "", "env": { "ANTHROPIC_AUTH_TOKEN": "", "ANTHROPIC_API_KEY": "", diff --git a/tests/unit/proxy/client/cli/test_auth_commands.py b/tests/unit/proxy/client/cli/test_auth_commands.py index 5d5ebcf5dfd..34a5dda0ad4 100644 --- a/tests/unit/proxy/client/cli/test_auth_commands.py +++ b/tests/unit/proxy/client/cli/test_auth_commands.py @@ -1501,18 +1501,18 @@ class TestLoginConfigClaude: assert "Configured Claude Code" not in result.output def test_flag_writes_the_settings_file_and_reports_success(self, tmp_path, monkeypatch): + monkeypatch.setenv("PATH", str(_fake_lite(tmp_path).parent)) result, settings_path, _backup_path = self._run_login(tmp_path, monkeypatch, ["--config-claude"]) assert result.exit_code == 0 written = json.loads(settings_path.read_text()) assert written["env"]["ANTHROPIC_BASE_URL"] == "https://test.example.com" assert written["env"]["ENABLE_TOOL_SEARCH"] == "true" - # The minted key goes in as a static token: an apiKeyHelper would make Claude Code spawn `lite` (and - # its keychain probe) on every credential refresh, which is what this flag used to write. assert written["env"]["ANTHROPIC_AUTH_TOKEN"] == "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.test.jwt" assert "apiKeyHelper" not in written assert f"Configured Claude Code: {settings_path} now routes through https://test.example.com." in result.output assert "run `lite login --config-claude` again after it expires" in result.output + assert "`lite login --pkce --config-claude` instead lets Claude Code renew the key" in result.output assert "the model Claude Code starts and resumes on" in result.output def test_flag_preserves_unrelated_settings_on_an_existing_file(self, tmp_path, monkeypatch): @@ -1613,6 +1613,58 @@ class TestLoginConfigClaude: assert "even though the CLI itself could not keep it" in result.output assert "You can now use the CLI without specifying --api-key" not in result.output + def _run_pkce_login(self, tmp_path, monkeypatch, path, stored): + settings_path = tmp_path / "claude" / "settings.json" + self._isolate_default_settings(tmp_path, monkeypatch) + with ( + patch("litellm.proxy.client.cli.commands.auth.run_pkce_login", return_value=_pkce_credential()), + patch("litellm.proxy.client.cli.commands.auth.load_token", return_value=None), + patch("litellm.proxy.client.cli.commands.auth.save_token", return_value=stored), + patch("litellm.proxy.client.cli.interface.show_commands"), + ): + result = self.runner.invoke( + login, + ["--pkce", "--config-claude"], + obj={"base_url": PKCE_BASE_URL}, + env={"CLAUDE_CONFIG_DIR": str(settings_path.parent), "PATH": path}, + ) + return result, settings_path + + def test_a_pkce_login_gets_a_helper_that_renews_the_key_instead_of_a_copy_that_expires(self, tmp_path, monkeypatch): + lite = _fake_lite(tmp_path) + result, settings_path = self._run_pkce_login(tmp_path, monkeypatch, str(lite.parent), SecretStored()) + + assert result.exit_code == 0, result.output + written = json.loads(settings_path.read_text()) + assert written["env"]["ANTHROPIC_BASE_URL"] == PKCE_BASE_URL + assert "ANTHROPIC_AUTH_TOKEN" not in written["env"] + assert str(lite.parent) in written["apiKeyHelper"] + assert written["apiKeyHelper"].endswith(f"--base-url {PKCE_BASE_URL} auth print-token") + assert "sk-cli-fresh" not in settings_path.read_text() + assert "`lite auth print-token`, which renews it before it expires" in result.output + + @pytest.mark.parametrize( + ("lite_on_path", "stored", "reason"), + [ + (False, SecretStored(), "`lite` is not on your PATH"), + (True, CredentialNotSaved("read-only ~/.litellm"), "even though the CLI itself could not keep it"), + (True, CredentialNotRecorded(), "even though the CLI itself could not keep it"), + ], + ids=["lite-not-on-path", "nothing-kept-it", "keychain-took-it-file-refused"], + ) + def test_a_pkce_login_lite_cannot_renew_for_claude_code_gets_the_static_key( + self, tmp_path, monkeypatch, lite_on_path, stored, reason + ): + path = str(_fake_lite(tmp_path).parent) if lite_on_path else str(tmp_path / "empty-path") + result, settings_path = self._run_pkce_login(tmp_path, monkeypatch, path, stored) + + assert result.exit_code == 0, result.output + written = json.loads(settings_path.read_text()) + assert written["env"]["ANTHROPIC_AUTH_TOKEN"] == "sk-cli-fresh" + assert "apiKeyHelper" not in written + assert reason in result.output + assert "run `lite login --pkce --config-claude` again after it expires" in result.output + def test_settings_failure_is_reported_without_claiming_login_failed(self, tmp_path, monkeypatch): settings_path = tmp_path / "claude" / "settings.json" settings_path.parent.mkdir(parents=True) @@ -1627,6 +1679,14 @@ class TestLoginConfigClaude: assert "Authentication failed" not in result.output +def _fake_lite(tmp_path): + lite = tmp_path / "bin" / ("lite.exe" if os.name == "nt" else "lite") + lite.parent.mkdir(exist_ok=True) + lite.write_text("") + lite.chmod(0o700) + return lite + + class _FakeHttpResponse: def __init__(self, status_code, payload): self.status_code = status_code diff --git a/tests/unit/proxy/client/cli/test_claude_settings.py b/tests/unit/proxy/client/cli/test_claude_settings.py index 9451598aa40..79ca1f8660e 100644 --- a/tests/unit/proxy/client/cli/test_claude_settings.py +++ b/tests/unit/proxy/client/cli/test_claude_settings.py @@ -3,6 +3,7 @@ import os import pathlib import shlex import stat +import subprocess import sys import time from concurrent.futures import ThreadPoolExecutor, TimeoutError as FutureTimeoutError @@ -25,6 +26,7 @@ from litellm.proxy.client.cli.commands.claude_settings import ( OWNED_ENV_KEYS, OWNED_TOP_LEVEL_KEYS, SETTINGS_FILE_OWNERS, + ApiKeyHelper, ClaudeSettingsError, KeepModel, SettingsFileOwner, @@ -35,6 +37,7 @@ from litellm.proxy.client.cli.commands.claude_settings import ( configure_claude_settings, install_statusline_script, configure_state_path, + lite_api_key_helper, merge_claude_settings, statusline_command, unconfigure_claude_settings, @@ -165,6 +168,34 @@ class TestConfigureClaudeSettings: assert not settings_path.exists() +class TestLiteApiKeyHelper: + @pytest.mark.skipif(sys.platform.startswith("win"), reason="runs the command through sh, as Claude Code does on POSIX") + def test_sh_runs_the_lite_on_path_against_this_proxy(self, tmp_path): + lite = tmp_path / "my tools" / "lite" + lite.parent.mkdir() + lite.write_text('#!/bin/sh\nprintf "%s\\n" "$0" "$@"\n') + lite.chmod(0o700) + + helper = lite_api_key_helper("https://proxy.example.com/", platform="linux", which=lambda name: str(lite)) + + assert helper is not None + ran = subprocess.run(["sh", "-c", helper.command], capture_output=True, text=True, check=True) + assert ran.stdout.splitlines() == [str(lite), "--base-url", "https://proxy.example.com", "auth", "print-token"] + + def test_quotes_every_token_for_cmd_on_windows(self): + helper = lite_api_key_helper( + "https://proxy.example.com", platform="win32", which=lambda name: r"C:\Program Files\lite\lite.exe" + ) + + assert helper is not None + assert helper.command == ( + r'"C:\Program Files\lite\lite.exe" "--base-url" "https://proxy.example.com" "auth" "print-token"' + ) + + def test_no_lite_on_path_means_no_helper(self): + assert lite_api_key_helper("https://proxy.example.com", which=lambda name: None) is None + + class TestConflictingOwnersOfTheSettingsFile: """Both `lite up` and `lite autoroute start` restore a backup when they stop. @@ -313,6 +344,14 @@ class TestMergeClaudeSettings: assert "model" not in merged assert not any(key in merged["env"] for key in ANTHROPIC_DEFAULT_MODEL_ENV_KEYS) + def test_a_helper_lands_top_level_and_every_static_credential_is_cleared(self): + settings = {"env": {"ANTHROPIC_AUTH_TOKEN": "sk-expired-login", "ANTHROPIC_API_KEY": "leaked"}} + merged = merge_claude_settings(settings, "http://127.0.0.1:4000/", HELPER) + assert merged["apiKeyHelper"] == HELPER.command + assert merged["env"]["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:4000" + assert "ANTHROPIC_AUTH_TOKEN" not in merged["env"] + assert "ANTHROPIC_API_KEY" not in merged["env"] + def test_keeps_existing_switch_values_and_unrelated_keys_without_mutating_the_input(self): settings = {"theme": "dark", "env": {"SOME_OTHER_VAR": "value", "ENABLE_TOOL_SEARCH": "false"}} merged = merge_claude_settings(settings, "http://127.0.0.1:4000", StaticToken("token-abc")) @@ -374,6 +413,7 @@ class TestMergeClaudeSettings: PROXY = "http://127.0.0.1:4000" ANTHROPIC = "https://api.anthropic.com" RELOGIN = StaticToken("sk-fresh-login") +HELPER = ApiKeyHelper("/usr/local/bin/lite --base-url http://127.0.0.1:4000 auth print-token") ORIGINAL = { "theme": "dark", "permissions": {"allow": ["Bash"]}, @@ -432,6 +472,15 @@ class _Rig: # to be one test each; the receipt's rules are what make them all come out right. UNDO_SCENARIOS = { "plain round trip": (ORIGINAL, [], ORIGINAL, {"kept": ()}), + "helper round trip": (ORIGINAL, [], ORIGINAL, {"kept": ()}, {"credential": HELPER, "model": KeepModel()}), + "helper with no file before": (None, [], None, {"file_removed": True}, {"credential": HELPER}), + "re-logins switching between the token and the helper keep the first snapshot": ( + ORIGINAL, + [{"credential": HELPER, "model": KeepModel()}, {"credential": RELOGIN, "model": KeepModel()}], + ORIGINAL, + {"kept": ()}, + {"credential": HELPER, "model": KeepModel()}, + ), "no file before": (None, [], None, {"file_removed": True}), "no env before": ({"theme": "dark"}, [], {"theme": "dark"}, {}), "null env before": ({"theme": "dark", "env": None}, [], {"theme": "dark", "env": None}, {}),