English · Deutsch
Desktop app for macOS and Windows that manages approved, project-specific LiteLLM keys in a local key file and assigns them to local project folders. Claude Code (VS Code, IntelliJ, CLI) then automatically uses the matching key in every project. Several projects open at the same time work independently of each other.
Assign once, never switch keys again. Claude Code fetches the matching key itself via keyzapper-helper,
even when KeyZapper is closed. The app explains this under “How it works”.
Screenshot with made-up sample data.
Claude Code ──apiKeyHelper──▶ keyzapper-helper ──▶ local key file
│
└──── requests with project key ────▶ LiteLLM ──▶ Amazon Bedrock
LLM costs have to be tracked per project and kept within project budgets. For this, a dedicated middleware in front of LiteLLM issues API keys per project. Each key carries its project's budget and allowed models, so every request made with it is booked to that project. KeyZapper makes sure Claude Code always uses the key of the project you are working in, so the costs land on the right project without anyone switching keys by hand.
- Profiles with name, LiteLLM endpoint (https; plain http only for a gateway on localhost), optional model alias and key. The key is stored exclusively in the local key file
keys.jsonin the app data folder (no Keychain or credential-manager prompts). - Assign project folders to a profile. The app only adds to
.claude/settings.local.jsonand excludes the file from Git via.git/info/exclude. - Status per project: active, differing, folder missing, key missing, conflicts with other settings. A summary shows what needs attention; Repair all writes the settings of every affected project again.
- Drag project folders from Finder or Explorer onto a profile to assign them.
- MCP servers (stdio, HTTP or SSE) defined once – or from templates such as GitHub, Notion or Sentry – and switched on per project. The app writes them into the repository's
.mcp.json(excluded from Git) and approves them in.claude/settings.local.json, so Claude Code loads them there automatically. Remote servers with OAuth (e.g. Weave-MCP via Entra ID or Keycloak) take a client ID, callback port and scopes; Claude Code handles the browser sign-in. - Central MCP server list: IT publishes the MCP servers as one JSON file on its own server (e.g. the SSO server); KeyZapper loads it and offers the servers read-only for every project (see Central MCP server list).
- Claude Tools page: installs Claude Code (CLI), its VS Code extension and IntelliJ plugin and Claude Desktop from Anthropic's official sources and connects Claude Desktop to a key or SSO profile (see Claude tools).
- Test connection against LiteLLM (invalid or blocked key, rate limit, budget, gateway unreachable).
- Remaining budget per key, as reported by LiteLLM (
/key/info): a bar that turns orange from 70 % and red from 90 % used, amount left of the limit and next reset, or the spend for keys without a limit. - Claude subscription profiles: projects use your Claude Pro, Max, Team or Enterprise plan through Claude Code's own login instead of a gateway key (see below).
- Claude in Microsoft 365: a profile can set up the Claude add-in for Excel, Word and PowerPoint behind the company gateway with Entra SSO (see below).
- Menu bar (macOS) or notification area (Windows) icon: a click shows usage at a glance – your Claude subscription's limits (session, week, per model) and every key's budget; a right-click switches a project's profile without opening the window. Closing the window keeps KeyZapper running there.
- Removing an assignment only removes the entries the app set itself.
- Sidebar with profiles, projects, MCP servers, Claude settings and backup. Everything can be changed directly – via the ⋯ menu or a right-click; keys can be copied and replaced.
- Update check against the GitHub releases with one-click installation; the version is shown in the app and under “About KeyZapper”.
- UI in English and German (follows the system language).
- Encrypted backup and restore of profiles, assignments and keys (
.kzbackup, password-protected). - Manageable via Intune: predefined profiles (including Claude in Microsoft 365), gateway allowlist, defaults, minimum CLI version, OneDrive backup, update check, central MCP server list, Claude tools page.
- macOS 14 or newer or Windows 10 or newer (with the WebView2 runtime)
- Claude Code ≥ 2.1.288 (VS Code extension or the
claudeCLI for IntelliJ). Older versions only read the project assignment at startup directly in the project folder; the app warns in that case.
- Create profile: name, LiteLLM endpoint, key and optionally the gateway model names for Opus, Sonnet and Haiku. Load models from gateway lists the models the key may use (LiteLLM
/v1/models) and fills the tiers. Profiles managed by IT are already there; just enter the key. - Assign project: choose a folder and select a profile. For Git repositories the assignment applies to the whole repository including subfolders and worktrees. Claude Code reads the project settings only at the root of the main checkout.
- Restart the Claude session in the project; in VS Code, start a new conversation or reload the window.
The overview shows every profile with endpoint, model and the assigned key (masked, e.g. ••••7f3a) along with all
assigned projects. For each project you can change the profile, reapply the settings and remove the assignment.
Copy key: The key is placed on the clipboard marked as confidential so that clipboard managers do not store it. After 60 seconds it is removed again, unless something else has been copied in the meantime.
Changing a key: “Change” replaces the key; this takes effect immediately for new sessions. Running sessions pick up the key after the helper cache expires (default 5 min), after an HTTP 401, or after a restart.
If a key is missing or blocked, requests fail. Claude Code never falls back to other credentials.
Profiles can authenticate via a static LiteLLM key (Key type) or via OIDC login (SSO type). SSO requires an OIDC-verifying proxy in front of LiteLLM that validates the token (access token by default) and injects the virtual key into requests.
SSO fields: Issuer (https URL), Client ID (public client, no secret), Scope (default openid profile offline_access),
Token type (Access token default, or ID token for gateways that expect the OIDC ID token as bearer token).
For Microsoft Entra ID use scope api://<app-id>/.default offline_access with access tokens; a refresh token is required.
With ID tokens the scope must include openid (Entra ID: also profile, otherwise the oid claim is missing) and offline_access;
the token's expiry comes from its exp claim.
Login: Sign In opens the system browser for Authorization Code flow with PKCE. The redirect URI is a loopback address
http://127.0.0.1:<random port>/callback. To register the redirect URI:
- Microsoft Entra ID: App registration › Mobile and desktop applications › Redirect URI:
http://127.0.0.1(Entra ignores the port for loopback redirects). - Keycloak: Public client › Standard flow › PKCE S256 › Valid redirect URI:
http://127.0.0.1/*.
Tokens: Refresh and access tokens are stored locally in sso-tokens.json in the app data folder (owner-only, 0600),
never in backups or via "copy key". The helper returns a cached access token or refreshes it once, serialized safely across parallel
sessions. Exit code 67 means the session expired; sign in again in KeyZapper.
Settings: Set CLAUDE_CODE_API_KEY_HELPER_TTL_MS in the profile's Environment field to a value below the token lifetime
(e.g., 900000 for 60–90 min tokens). For long streams over a gateway, also set API_TIMEOUT_MS,
CLAUDE_STREAM_IDLE_TIMEOUT_MS, CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS.
Limitations: SSO profiles do not support the Budget-Killer pool or key copying. Model loading, test connection and the budget display (one budget per tenant, see below) use the access token.
A gateway that serves several tenants (teams, cost centres) lists its models as <tenant>/<model>, for example
acme/claude-sonnet-5-5 and globex/claude-sonnet-5-5. A person with access in two tenants still keeps one profile and
one login: the same SSO token, the same helper, the same base URL. KeyZapper reads the model list from the gateway
(/v1/models) together with the budgets; once it contains two or more tenants, every project row shows a Tenant selection.
Choosing a tenant replaces only the four model settings of that project (ANTHROPIC_MODEL and
ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU}_MODEL) with the models of that tenant: each model of the profile moves to
<tenant>/<name> if the tenant has it, otherwise the tenant's newest model of that tier is used. The default model keeps tier
aliases such as sonnet or opusplan; a model ID moves along, or falls back to the tenant's Sonnet model. The helper
(--profile <ID>) and ANTHROPIC_BASE_URL stay the same, so Claude Code in that project calls the chosen tenant after one
sign-in. As in the profile returns to the profile's own models.
The choice is saved with the project assignment and survives Apply again, profile edits and backups; assigning the project to another profile clears it. Subscription profiles have no tenants.
A profile of type Claude subscription has no endpoint and no key: assigned projects use the Claude account Claude Code is
logged in with (/login). KeyZapper writes apiKeyHelper, ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN
and the gateway model variables as empty values into .claude/settings.local.json, so a default profile or shell variables do
not apply there; an optional default model (e.g. opus) goes into ANTHROPIC_MODEL.
For plan and usage, KeyZapper reads Claude Code's login (macOS keychain item "Claude Code-credentials", otherwise
~/.claude/.credentials.json) and asks api.anthropic.com/api/oauth/usage, like Claude Code's /usage. The token is never
refreshed, stored or copied; while it has expired (Claude Code renews it when it runs), the last known values are shown. The
endpoint is not a public API and may change. The gateway allowlist does not apply to these profiles, and the repository analysis
needs a gateway profile.
A profile can also set up Claude for Microsoft 365, the Claude add-in for Excel, Word and PowerPoint, behind the company
gateway. KeyZapper does this for the profile that has Claude in Office switched on: in the profile editor, or through the
Office dict of a managed profile (see Distribution via Microsoft Intune). If several
profiles have it on, those defined by IT come first, then the first of your own.
What it does: KeyZapper loads Anthropic's manifest template (https://pivot.claude.ai/manifest.xml, only while Claude in Office
is switched on), sets the add-in ID of your company and appends the gateway and Entra parameters to the add-in's two page addresses: gateway_url,
gateway_api_format=anthropic, entra_sso=1, graph_client_id, entra_scope, gateway_auth_source=entra and, if set,
disabled_features. The result is sideloaded:
- macOS:
<add-in ID>.manifest.xmlin theweffolder of each installed app below/Applications(Excel, Word, PowerPoint), that is~/Library/Containers/com.microsoft.<App>/Data/Documents/wef. - Windows: the file in
%LOCALAPPDATA%\KeyZapper\office, registered as a value named after the add-in ID underHKCU\SOFTWARE\Microsoft\Office\16.0\Wef\Developer.
Entra only, no secret: the add-in signs in through Microsoft Entra SSO. The manifest contains no secret, and KeyZapper never reads or writes the add-in's own storage. The Entra app registration and the gateway route that accepts its tokens belong to the gateway side; KeyZapper only passes their IDs.
Fields: gateway URL (https; its host must be allowed by AllowedGatewayHosts), Entra client ID, Entra scope
(api://<client ID>/access_as_user), add-in ID and, optionally, add-in features to switch off (comma-separated). The add-in ID is
a GUID of your own in lowercase; the ID of the marketplace add-in is refused, so the sideloaded add-in never takes its place.
Restart Office once, then open Claude via Insert → My Add-ins. The profile card shows the apps it was set up for, or why that did not work. On macOS the first write makes the system ask whether KeyZapper may access data of other apps (the Office containers); allow it. If it was denied, the profile card shows the error, and a change of the profile or Refresh status tries again.
When it writes: only if something changed: the profile's Office settings, Anthropic's template or the installed Office apps.
KeyZapper keeps its own record in state.json and never reads the Office folders to find out. Without a connection it uses
the last template it loaded. Without one, or if the template does not look like Anthropic's, nothing is written and an
existing manifest stays.
Removing: switching Claude in Office off, deleting the profile or deactivating KeyZapper removes KeyZapper's own manifest (on Windows also its registry value) from Office. Files of other add-ins stay.
Quitting or uninstalling KeyZapper leaves the manifest in place, because only KeyZapper removes it, and only while it runs. Before uninstalling, switch Claude in Office off in the profile or deactivate KeyZapper; that removes the manifest (on Windows also its registry value) first.
Office may cache sideloaded manifests. If a change (another gateway, another add-in ID, switched off) does not show up after the restart, restart Office once more or, if that does not help, clear Office's add-in cache. This is a hint: KeyZapper neither checks nor touches that cache.
Sideloading is Microsoft's route for developing and testing add-ins, not for distributing them in production. For that, Microsoft supports central deployment of the manifest through the Microsoft 365 admin center. Use the same add-in ID there, so both routes refer to the same add-in.
Setup (once): The key goes to the helper via stdin and ends up only in the key file keys.json. The app writes only references into the project.
Runtime (every Claude request): Claude Code fetches the key for each project itself via the helper, even when the app is closed.
The full view with explanations is at docs/diagrams/keyzapper-flow.html.
The app writes to <project>/.claude/settings.local.json:
| Key | Value |
|---|---|
apiKeyHelper |
'/Applications/KeyZapper.app/Contents/MacOS/keyzapper-helper' credential --profile <UUID> on macOS, the quoted path of keyzapper-helper.exe in the install folder on Windows (Key and SSO profiles); '/mnt/c/…/keyzapper-helper.exe' credential --profile <UUID> for projects in WSL |
env.ANTHROPIC_BASE_URL |
LiteLLM endpoint of the profile |
env.ANTHROPIC_DEFAULT_OPUS_MODEL, …_SONNET_MODEL, …_HAIKU_MODEL, env.ANTHROPIC_MODEL |
Gateway model names of the profile (if set), e.g. eu.anthropic.claude-sonnet-5-… |
further env.* |
Additional environment variables of the profile, e.g. CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 for Bedrock via LiteLLM |
env.ANTHROPIC_API_KEY, env.ANTHROPIC_AUTH_TOKEN |
"". This neutralizes inherited values from the IDE or shell that would otherwise produce mixed auth headers. |
Existing settings are preserved. Changes are atomic and idempotent: setting up repeatedly changes nothing.
Conflicts that prevent setup:
- Managed Claude settings that set
apiKeyHelperorANTHROPIC_* CLAUDE_CODE_USE_BEDROCK,_VERTEXor_FOUNDRYin any settings level- foreign values for the same keys in
settings.local.json - a checked-in
settings.local.json
Helper interface: keyzapper-helper credential|store|status|delete --profile <UUID>. The key flows only via stdin and stdout,
never via arguments or logs.
| Exit code | Meaning |
|---|---|
| 0 | ok |
| 64 | usage |
| 65 | unknown profile |
| 66 | key missing |
| 67 | session expired (SSO only; sign in again) |
| 70 | internal |
| 77 | key store (keys.json) unreadable or not writable |
| 78 | metadata corrupt, endpoint not https (http only for localhost) or not in AllowedGatewayHosts |
Metadata without keys is stored in state.json in the app data folder, the keys in keys.json next to it: ~/Library/Application Support/KeyZapper on macOS (owner-only), %LOCALAPPDATA%\KeyZapper on Windows (user profile folder). Keys from the former Keychain-based version are offered for a one-time move on macOS (macOS may ask for permission once per key).
A project folder inside a WSL distribution (\\wsl.localhost\<distro>\home\…, also the older \\wsl$\…) is assigned like any
other folder: pick it in the folder dialog under "Linux" or drag it onto the window. Git root, status and the Git exclude
entry come from the distribution's own git (wsl.exe -d <distro> --exec git …), not from Windows git, which reports
"dubious ownership" on these shares.
Claude Code inside WSL is a Linux process and runs apiKeyHelper with /bin/sh, so settings.local.json in such a
project contains the Windows helper by its mount path, quoted for sh:
"apiKeyHelper": "'/mnt/c/Users/<user>/AppData/Local/Programs/KeyZapper/keyzapper-helper.exe' credential --profile <UUID>"The helper runs through WSL interop as a Windows process and reads keys.json from %LOCALAPPDATA%\KeyZapper as usual;
the key never enters the distribution's file system. Requirements: WSL interop and the drive automount must be on (the
defaults; [interop] enabled=true and [automount] enabled=true with the default root /mnt in /etc/wsl.conf), and git
must be installed in the distribution for the Git root to be detected (otherwise the picked folder itself is assigned).
Every Git tag X.Y.Z builds the packages KeyZapper-X.Y.Z.pkg (macOS) and KeyZapper-X.Y.Z.msi (Windows) via CI and attaches both to the GitHub release (see Release).
macOS: create the app: Apps › All apps › Create › macOS app (PKG). This is the unmanaged PKG type, which also accepts unsigned packages; it requires the Intune Management Agent ≥ 2308.006.
- Minimum OS: macOS 14
- Detection rules › Included apps:
io.github.bl0rb.keyzapperwith the package version, “Ignore app version” = No
Windows: create the app: Apps › All apps › Create › Line-of-business app, upload the .msi (per-machine install to Program Files).
Signing: Keys are not in the Keychain, so signing does not affect key access. For macOS, SIGN_IDENTITY and INSTALLER_IDENTITY
(desktop/scripts/build-pkg.sh) sign with a Developer ID; without them the build is ad-hoc signed.
Uninstall: Intune has no uninstall assignment for PKG apps. First choose “Remove assignment” in the app,
then delete /Applications/KeyZapper.app. On Windows, uninstall the MSI via Intune or Apps & features.
macOS: Devices › Configuration › Create › macOS › Templates › Preference file, Preference domain name io.github.bl0rb.keyzapper.
Template with every key: docs/intune/io.github.bl0rb.keyzapper.plist. It contains only
key-value pairs without the <plist>/<dict> wrapper, as Intune requires.
Windows: The same keys are read as registry values under HKLM\SOFTWARE\Policies\KeyZapper (machine policy wins) or HKCU\SOFTWARE\Policies\KeyZapper:
strings as REG_SZ, lists as REG_MULTI_SZ, switches as REG_DWORD 0/1, ManagedProfiles as a JSON array in a REG_SZ.
Template with every key: docs/intune/keyzapper-windows.reg (deploy e.g. via PowerShell script or Settings catalog).
Important: For users receiving SSO profiles via managed settings, do not set apiKeyHelper, env.ANTHROPIC_BASE_URL,
ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN in managed-settings.json (or managed-settings.d/*.json). Managed settings
outrank project settings; KeyZapper aborts binding on conflict.
| Key | Type | Effect |
|---|---|---|
ManagedProfiles |
Array of dicts: Name, Endpoint, optional OpusModel, SonnetModel, HaikuModel, ModelAlias, Environment (dict), ID, Type (apiKey default or oidc), OIDCIssuer, OIDCClientID, OIDCScope, OIDCTokenType, Office, ClaudeDesktop (dicts, see below) |
Profiles are created automatically and cannot be edited or deleted; developers only enter the key (or sign in for SSO) and may switch on Claude in Office and Claude Desktop (SSO) for the profile where IT sets neither (see below). Without ID the profile ID is derived from Name, so renaming creates a new profile. For SSO (oidc type), OIDCIssuer and OIDCClientID are required; OIDCScope defaults to openid profile offline_access; OIDCTokenType is access (default) or id, other values discard the profile. |
ClaudeDesktop (inside a ManagedProfiles entry) |
Dict: OIDCIssuer, OIDCClientID, optional GatewayURL (default: the profile's Endpoint), Scopes, BearerTokenType (id_token default or access_token), CredentialKind (external-idp default or interactive), Config (dict of further Claude Desktop keys), AutoApply (Bool, default false) |
Claude Desktop signs in itself with the gateway's OIDC client when this profile is chosen for it (see Claude tools). The keys map to Claude Desktop's configuration: GatewayURL → inferenceGatewayBaseUrl, OIDCIssuer/OIDCClientID/Scopes/BearerTokenType → the issuer, clientId, scopes and bearerTokenType of the OIDC block, CredentialKind → inferenceCredentialKind; inferenceProvider: gateway and appendOfflineAccess: true are always written, everything else (telemetry, banner, allowed hosts, …) goes into Config. Without the dict, developers may fill in Claude Desktop (SSO) in the profile themselves; the dict from IT replaces their entry. external-idp needs Claude Desktop 2.7032.0 or newer; set interactive while older versions are in use. A block with unusable values (also an unknown CredentialKind) is kept; KeyZapper then writes nothing for Claude Desktop. |
Office (inside a ManagedProfiles entry) |
Dict: Enabled (Bool, default true), AddinID, GatewayURL, EntraClientID, EntraScope, DisabledFeatures (array or comma-separated string) |
Sets up Claude in Microsoft 365 from this profile. Without the dict, developers may switch on Claude in Office in the profile themselves; the dict from IT replaces their entry. Values are trimmed. A block with unusable values is kept and reported on the profile card; nothing is written then. |
AllowedGatewayHosts |
Array of strings (host or *.domain) |
Profiles only for these hosts. The helper does not release keys for other hosts (exit 78). Applies to the gateway host only; the IdP host need not be listed. Empty means no restriction. |
DefaultEndpoint, DefaultModelAlias |
String | Prefill when creating your own profiles |
MinimumClaudeCodeVersion |
String | Threshold for the warning about outdated Claude CLIs (default 2.1.288) |
OneDriveBackup |
Bool | Backup of profiles and assignments to OneDrive (see below) |
BackupDirectory |
String, ~ allowed |
Explicit backup folder; enables the backup even without OneDriveBackup |
UpdateCheckEnabled |
Bool (default true) |
In-app update check. When distributing via Intune, set to false, otherwise Intune may overwrite a newer version that was installed by the user. |
AllowKeyExport |
Bool (default true) |
Whether keys may leave the key store via the app. false: no copying to the clipboard; backups contain profiles and assignments only. |
ManagedMcpServersURL |
String (https URL) | Address of the central MCP server list (see Central MCP server list). |
ClaudeToolsEnabled |
Bool (default true) |
Shows the Claude Tools page for installing Claude Code, its IDE plugins and Claude Desktop. |
ClaudeDesktopAutoInstall |
Bool (default false) |
Installs a missing Claude Desktop in the background from Anthropic's official sources, also with the Claude Tools page hidden (see Claude tools). |
ProxyURL |
String (http://host:port, optionally user:password@) |
Proxy for KeyZapper's own internet traffic: the update check and installer downloads from github.com, the Claude installers from claude.ai. Without it, KeyZapper uses the proxy environment variables (HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, honouring NO_PROXY) and otherwise the system proxy (macOS network settings, Windows internet options; a PAC file is not evaluated). Gateway and identity-provider calls are not routed through it. |
IgnoreDownloadCertificateErrors |
Bool (default false) |
The update check and the downloads accept certificates the system does not trust, for a proxy with TLS inspection whose root certificate is not installed on the device (error "The certificate was not trusted"). Only KeyZapper's own internet traffic is affected; the installers stay protected by the SHA-256 checksum and minisign signature (KeyZapper) and by Anthropic's code signature (Claude Desktop). Prefer installing the proxy's root certificate on the device. |
Test locally (user level; values managed via Intune take precedence):
defaults write io.github.bl0rb.keyzapper AllowedGatewayHosts -array litellm.firma.exampleThe app backs up profiles and project assignments to ~/Library/CloudStorage/OneDrive-<Company>/KeyZapper/keyzapper-backup.json (macOS) or into the KeyZapper folder of the OneDrive folder (Windows).
A business account takes precedence over “OneDrive-Personal”. Keys are never backed up. On a new computer the app offers
to restore or discard the backup (“Restore” or “Discard”). Assignments are only applied for existing folders; the keys
have to be entered again. As long as a found backup has been neither restored nor discarded, it is not overwritten.
IT maintains the MCP servers in one JSON file on its own server and distributes only its address via Intune
(ManagedMcpServersURL). The file uses Claude Code's .mcp.json format; template:
docs/intune/mcp-servers.example.json.
{
"mcpServers": {
"weave": { "type": "http", "url": "https://weave.firma.example/mcp",
"oauth": { "clientId": "c1abe…", "callbackPort": 8976, "scopes": "api://weave/mcp.read" } },
"wiki": { "type": "http", "url": "https://wiki.firma.example/mcp", "headers": { "X-Tenant": "firma" } },
"fetch": { "type": "stdio", "command": "uvx", "args": ["mcp-server-fetch"] }
}
}- KeyZapper loads the list at startup, every 10 minutes, after an SSO sign-in and via Reload on the MCP Servers page.
The server answers
GETwith200and the JSON (at most 1 MB);401/403is shown as "sign-in required". - Sign-in: If an SSO profile is signed in whose gateway or identity provider has the same host as the list, KeyZapper
sends its token as
Authorization: Bearer …(the token type of the profile). The server can thus answer per user or group. The token only goes to hosts that receive it anyway. - The servers appear with the badge Managed by IT: developers switch them on per project but cannot edit or delete them. Changes to the list are written into the projects using them; servers IT removes from the list leave the projects.
- The last list fetched stays in
mcp-catalog.jsonin the app data folder, so the servers keep working offline; a failed fetch is shown on the page and the previous list stays in effect. - Only
httpsaddresses (plain http only for localhost), also for remote servers on the list. Entries with an invalid name, without command or URL are left out and listed on the page; so is an entry with the name of a developer's own server. - Secrets do not belong in the file; use
${NAME}references (Claude Code fills them from the environment) or OAuth.
The Claude settings page in the sidebar checks ~/.claude/settings.json for problems Claude Code accepts
silently: invalid JSON (validated with the same strict JSON.parse as Claude Code, e.g. trailing commas), plaintext keys,
an endpoint without a key, non-text values in env, provider switches that bypass LiteLLM, model variables and fixed
model IDs instead of an alias. A banner shows problems at any time.
- Repair / Create makes the file valid, removes plaintext keys and turns
envvalues into text. A missing file is created. Before every change KeyZapper saves a backupsettings.json.keyzapper-<time>.bak. - Default profile writes a profile into
~/.claude/settings.json, so Claude Code uses it in all folders without their own assignment instead of a plaintext key or the normal login. Assigned projects keep their own profile.
The Claude Tools page (hidden with ClaudeToolsEnabled = false) shows what is installed and installs, without administrator rights:
| Tool | Source | Installed to |
|---|---|---|
| Claude Code (CLI) | Anthropic's native installer (curl -fsSL https://claude.ai/install.sh | bash, Windows irm https://claude.ai/install.ps1 | iex) |
~/.local/bin/claude, updates itself |
| Claude Code for VS Code | code --install-extension anthropic.claude-code (VS Code Marketplace) |
VS Code of the user |
| Claude Code for IntelliJ IDEA | idea installPlugins com.anthropic.code.plugin (JetBrains Marketplace); IntelliJ must be closed |
every IntelliJ IDEA found (also Toolbox installs) |
| Claude Desktop | .dmg from claude.ai/api/desktop/darwin/universal/dmg/latest/redirect (macOS; checks Anthropic's Developer ID Q6L2SF6YDW before copying to /Applications or ~/Applications), .msix via Add-AppxPackage (Windows) |
Applications folder / current user |
Sign-in: Claude Code in the terminal, in VS Code and in IntelliJ uses the profile of assigned projects and the default
profile elsewhere (key, SSO or Claude subscription). For key and SSO profiles, turn on Disable Login Prompt
(claudeCode.disableLoginPrompt) in VS Code; the page opens that setting. If IntelliJ does not find claude, enter the path
shown on the page under Settings › Tools › Claude Code [Beta] › Claude command.
Claude Desktop with a profile: Choose a key or SSO profile and Apply. KeyZapper writes one configuration file for
Claude Desktop's third-party mode into its configuration library (~/Library/Application Support/Claude-3p/configLibrary,
%LOCALAPPDATA%\Claude-3p\configLibrary) and selects it in _meta.json:
{
"inferenceProvider": "gateway",
"inferenceGatewayBaseUrl": "https://litellm.firma.example",
"inferenceCredentialKind": "helper-script",
"inferenceCredentialHelper": "/Applications/KeyZapper.app/Contents/MacOS/keyzapper-helper",
"inferenceCredentialHelperArgs": ["credential", "--profile", "<UUID>"],
"inferenceCredentialHelperTtlSec": 300,
"inferenceModels": [{ "name": "eu.anthropic.claude-sonnet-5-team", "anthropicFamilyTier": "sonnet" }]
}Claude Desktop thus gets the key or SSO token from keyzapper-helper, like Claude Code; no key is in the file. The
helper TTL follows CLAUDE_CODE_API_KEY_HELPER_TTL_MS of the profile (default 300 s). Then quit and reopen Claude Desktop
and choose to start with this configuration on the sign-in screen. Normal sign-in (claude.ai) removes the entry again
and applies the configuration that was applied before, if it still exists. If the profile changes, KeyZapper updates the
file. A Claude Desktop configuration IT deploys via MDM profile (com.anthropic.claudefordesktop) or registry
(HKLM\SOFTWARE\Policies\Claude) takes precedence when it sets more than the app's update, restart and proxy keys; KeyZapper
then writes nothing and the page points this out. Deactivating KeyZapper removes the entry and activating writes it again.
Claude Desktop set up by IT: In the ClaudeDesktop dict of a managed profile, Config adds further keys of Claude
Desktop's configuration reference to the entry (native
types, e.g. disableDeploymentModeChooser, coworkEgressAllowedHosts). The sign-in keys KeyZapper derives win; keys with
secrets, headers, local programs or credential files and bootstrap keys are refused, and then nothing is written. With
AutoApply KeyZapper writes and applies the entry without a click and writes it again at start and on refresh if it is
missing or was changed (only one managed profile may set it). In between the user can still change it, so nothing in it is
enforced; keys that must be enforced stay in MDM. With ClaudeDesktopAutoInstall KeyZapper installs a missing Claude Desktop
in the background after writing the configuration, independent of ClaudeToolsEnabled; a failed installation is tried again
on Refresh status.
Claude Desktop with its own SSO sign-in: If the gateway has its own OIDC client for Claude Desktop (another client ID or
gateway route than Claude Code), switch on Claude Desktop (SSO) in the profile and enter the issuer, the client ID and
optionally the gateway URL, the scopes and the token type (id_token default, access_token needs the gateway's scopes).
KeyZapper then writes the external-IdP sign-in instead of the helper (inferenceCredentialKind: external-idp,
inferenceIdpOidc; read by Claude Desktop 2.7032.0 and newer): Claude Desktop signs in in the browser, keeps its token itself
and lists the gateway's models (/v1/models). No key or token is written. For older Claude Desktop versions choose Older than
2.7032.0 in the profile's Claude Desktop version field: KeyZapper then writes the older spelling (interactive,
inferenceGatewayOidc), which newer versions read as the same sign-in. IT sets this with a ClaudeDesktop dict in
ManagedProfiles (CredentialKind: external-idp or interactive).
Trying it on a managed profile: A profile from Intune can still get Claude in Office and Claude Desktop (SSO) from the
developer, as long as IT's entry has no Office or ClaudeDesktop dict: Edit opens the profile with only those two sections
enabled, and the settings survive the next sync with Intune and a restart. Once IT adds the dict, it replaces the developer's
settings and locks the section; a dict IT removes again stays as the developer's own until they switch it off.
The switch at the bottom of the sidebar deactivates KeyZapper: it removes its entries from all projects and from
~/.claude/settings.json, so Claude Code uses its normal login everywhere. The assignments stay saved and are written
again when activating. Claude in Microsoft 365 is removed from Office while KeyZapper is deactivated and set up again on activation.
Export Backup… on the Backup page writes profiles, project assignments and keys into a .kzbackup file,
encrypted with a password of at least 12 characters. Import Backup… restores them on the same or another computer:
profiles and keys with the same ID are overwritten, and projects are assigned if their folder exists. The password is
stored nowhere – without it the backup cannot be restored.
Encryption: AES-256-GCM with a key derived via PBKDF2-HMAC-SHA256 (600,000 iterations, random salt). The file
parameters are authenticated, so a wrong password or a modified file is detected. The file is saved with permissions
0600. With AllowKeyExport = false the backup contains no keys. Unlike the automatic OneDrive backup (never keys),
this backup is created manually and on demand.
On startup the app checks the latest GitHub release; you can also check manually via
KeyZapper › Check for Updates… or the version line at the bottom of the app. If a newer version is available, “Install”
downloads the installer (.pkg on macOS, .msi on Windows), verifies the SHA-256 checksum published by GitHub and the release's
minisign signature (<installer>.minisig) against the public key built into the app (desktop/update-key.pub),
then opens the system installer. Without a checksum or a valid signature the update is refused; the signed file name must match, so an
older signed package cannot pass as a newer one.
Administrator rights are required. Packages are only downloaded from github.com. The installed version is shown at the bottom of the
app and under KeyZapper › About KeyZapper.
With Intune, UpdateCheckEnabled = false turns the check off. Updates then arrive as a new package in Intune.
Behind a company proxy the check and the download use the proxy from ProxyURL (Intune), else the proxy environment variables, else
the system proxy. A failed check names the proxy it went through. If the proxy inspects TLS with a certificate the device does not
trust, install its root certificate on the device, or set IgnoreDownloadCertificateErrors for the check and the downloads.
- One profile per Git repository; subfolders and worktrees cannot be assigned differently.
- If Claude is started outside the assigned area (e.g. in a subfolder of a non-Git folder), it uses the developer's default sign-in.
- The IntelliJ integration has not yet been verified in the pilot.
desktop/core Rust library keyzapper-core: data model, metadata, key store, helper logic, Claude settings, Intune configuration, backup
desktop/src-tauri Tauri app (macOS, Windows) and keyzapper-helper (apiKeyHelper for Claude Code)
desktop/ui Web interface (HTML, JS, CSS)
desktop/locales English translations (German source strings)
desktop/scripts build-pkg.sh (macOS), build-msi.sh (Windows), l10n_check.py
Tests:
cd desktop && cargo test -p keyzapper-coreRun the app in development mode (needs Rust and Node.js):
cd desktop && npm ci && npm run devBuild the installer locally (desktop/dist/KeyZapper-<version>.pkg on macOS, .msi on Windows in Git Bash):
cd desktop && VERSION=1.0.0 scripts/build-pkg.shcd desktop && VERSION=1.0.0 scripts/build-msi.shA tag in the format X.Y.Z starts .github/workflows/release.yml. The workflow runs the
tests, builds KeyZapper-X.Y.Z.pkg (macOS) and KeyZapper-X.Y.Z.msi (Windows), signs both with minisign and publishes them with
their .minisig files in one GitHub release. Signing needs the repository secret MINISIGN_SECRET_KEY (the secret key matching
desktop/update-key.pub); without it the workflow stops instead of publishing unsigned installers.
A tag like X.Y.Z-beta.N creates a pre-release, which is only offered with the Beta versions switch in the sidebar
(on by default while a beta is installed).
git tag 1.0.0git push origin 1.0.0MIT © 2026 bl0rb
