Use this guide to install the Claude Code Helper so that Claude Code routes its traffic through the F5 Workforce AI Security Gateway and Model Router. The helper is a cross-platform, zero-dependency compiled binary. It replaces Claude Code's static Anthropic API key with an OAuth 2.0 device flow, and exports the OS-trusted certificate authority (CA) certificates Claude Code needs to trust TLS inspection. After you complete this guide, Claude Code authenticates through the gateway on its own, at the start of every session.

The Claude Code Model Router must already be on before the helper can route traffic. See Configure the Claude Code Model Router.

Before you begin, make sure you have:

On Linux, the helper stores credentials using one of three backends. It tries each in this order: the secret-tool utility, the kernel keyring (keyctl), then an opt-in plaintext file for containers where neither is available.

Install at least one of the first two before you install the helper:

The helper is available from Workforce AI Security support as a compiled binary for Windows, macOS, and Linux. The right method depends on who installs it:

The PKG and MSI installers are covered in Deploy with the macOS installer and Deploy with the Windows installer. Manual deployment for all platforms is covered in Distribute configuration to managed devices.

Download the compiled binary for your platform and architecture, then run it with the install flag. For example, on macOS (Apple Silicon):

This authenticates the current developer and configures Claude Code. On Windows, run the matching .exe instead:

The install command:

To skip confirmation prompts, add the --yes flag (short form -y):

This installs the helper without prompts, which is useful in scripts or provisioning workflows.

Before installing, the helper checks for environment variables that would block correct routing through the Workforce AI Security Gateway. If it detects a conflict, it stops the install and lists the conflicts. Blocked variables include:

To turn off detected conflicts automatically, add the --force flag:

This renames each conflicting variable, by adding the prefix SP_DISABLE_, in the settings file where it was found. The helper can't rename a variable set in the shell environment. It shows a warning with instructions to unset that variable yourself.

To see a full diagnostic of all detected configuration issues without making changes, run claude-code-helper --report. To install without prompts while also fixing conflicts, combine both flags with --yes:

Run the diagnostic report to confirm the helper installed correctly:

The report lists the current apiKeyHelper and NODE_EXTRA_CA_CERTS settings, the authentication state, and a Permissions Audit section. That section checks runtime directory ownership and file permissions.

Then start a Claude Code session. On first use, the helper opens a browser window for a one-time device login. After that login completes, Claude Code sends requests through https://gateway.surepath.ai. Later sessions don't prompt for an API key.

To remove the helper and revert Claude Code settings, run the installed binary:

The uninstall command removes the installed binary and stored credentials from the OS credential manager. It reverts only the settings keys that install wrote, and keeps user-added allow rules, other deny entries, and all other env and hooks settings. It also keeps log files, backup files, and the CA certificate file. It creates a timestamped backup of settings.json before making any changes.

To delete stored credentials (access token, refresh token, and cached auth URL) without a full uninstall:

This forces re-authentication on the next Claude Code session, and it keeps the installation, settings, and CA certificates in place. Use it to troubleshoot authentication issues or to switch tenant accounts. The short alias is -cc.

To generate a support bundle with logs, configuration, and a diagnostic report, run:

The short alias is -cl. This command creates a zip file on the desktop with filtered log files, the current --report output, and configuration details. It excludes credentials. Share the bundle with Workforce AI Security support. Each file in the zip is capped at 10 MB.

The helper exports OS-trusted CA certificates to ~/.surepath/claude-code-helper/certs/extra-ca-certs.pem at the start of each session, using the SessionStart hook. The NODE_EXTRA_CA_CERTS environment variable points to this path. This lets Claude Code trust certificates installed at the OS level, including the Workforce AI Security CA certificate that TLS inspection needs.

The export result is cached for 24 hours. To force a refresh before the cache expires:

If your organization handles authentication separately and only needs the CA certificate configured, use cert-only mode:

This writes only env.NODE_EXTRA_CA_CERTS to ~/.claude/settings.json and leaves all other settings untouched. The short alias is -co.

For macOS deployments, Workforce AI Security provides pre-built PKG installer packages. These support both Apple Silicon (ARM64) and Intel (x64) architectures. The installer filenames follow this pattern:

Each PKG installs two files to /Library/Application Support/ClaudeCode/:

The installer, on its own:

This means MDM admins don't need a separate post-install script for permission or quarantine handling.

The installer shows as Workforce AI Security - Claude Code Helper in the macOS Installer app. It needs administrator privileges, and it installs to the local system domain only, not to user home directories.

The macOS binaries and PKG installers are code-signed with a Developer ID Application certificate, and Apple notarizes them, so Gatekeeper doesn't block them.

For Windows deployments, Workforce AI Security provides pre-built MSI installer packages, built with the WiX Toolset. These support both x64 and ARM64 architectures. The installer filenames follow this pattern:

Each MSI installs two files to C:\Program Files\ClaudeCode\:

The MSI bundles the interactive OAuth (user-authenticated) variant of managed-settings.json, which fits most desktop deployments.

MSI is the native deployment format for Microsoft Intune, Configuration Manager, and Group Policy Software Installation. To deploy through Intune:

Intune handles install, detection, and uninstall using the MSI's own ProductCode and UpgradeCode. It needs no PowerShell wrapper or repackaging. Other MDM tools that support MSI deploy it the same way.

The MSI, and the EXE binary inside it, are Authenticode-signed. This meets Windows security requirements for MDM-deployed executables, with no manual trust step.

For enterprise or fleet-wide deployments, deploy a managed-settings.json file alongside the helper binary. Claude Code reads this file at startup and treats its values as organization-level defaults. Individual user settings can't override these defaults.

On macOS and Windows, the PKG and MSI installers described earlier handle this deployment on their own. Use the steps in this section for Linux fleets, or when you need to deploy the binary and managed settings by hand on any platform.

When developers start Claude Code, authentication and certificate export happen on their own. Workforce AI Security support provides pre-built managed-settings.json files for each supported platform and distribution format.

In every case, the managed-settings.json file must use absolute system paths. It doesn't support the ~ shortcut or %USERPROFILE% expansion.

The PKG and MSI installers each include a default managed-settings.json, set up for the standard Workforce AI Security gateway deployment. This default configuration fits most organizations. To change permissions, environment variables, hooks, or the gateway URL, use one of these options.

If you deploy through the macOS PKG installer, its post-install script sets executable permissions for you. The rest of this section applies only when you deploy the binary by hand, outside a PKG.

On macOS and Linux, the helper binary needs its executable bit set, or Claude Code can't run it. MDM deployment tools, including Jamf and Intune, typically don't keep POSIX file permissions when they copy or download files to managed machines. The binary arrives on the device with default permissions that don't include the executable bit, even when the source file was executable.

Without the executable bit, Claude Code fails to call the helper at session start. The apiKeyHelper call and the SessionStart hook both return a Permission denied error, and developers can't authenticate. Developers often see this as an API key or authentication error, with nothing pointing to a file permission problem.

To prevent this, add a chmod command to the MDM post-install script or package configuration, run right after the binary is deployed:

Running chmod in the post-install step sets the permission on every managed machine, with no manual work needed. To confirm the permission is set correctly on a device, run:

The output shows -rwxr-xr-x at the start of the line. If it shows -rw-r--r-- or similar, without the x bits, the binary isn't executable.

On macOS, a binary downloaded from the internet, instead of deployed through a signed package, might carry a quarantine extended attribute (com.apple.quarantine). Gatekeeper uses this attribute to block execution. This is separate from file permissions. To check for and remove the attribute:

Binaries deployed through the Workforce AI Security signed and notarized PKG installer don't get this attribute, and their executable bit is set for you. The PKG installer is the recommended deployment method for macOS.

A permission error when writing certificates or credentials can happen after MDM deployment, when an administrator account created the runtime directories. If the helper reports this error, run the fix-permissions command with elevated privileges.

The short alias is -fp. This command scans the affected directories, confirms the changes, and corrects ownership. Afterward, the current user can write to the required paths.

Important: The helper blocks the --install, --uninstall, --upgrade, --cert-only, --clear-credentials, and --api-key commands when run as root or Administrator. Run those commands as the target user. Use --fix-permissions with elevation only for the repair step.

Symptom: Claude Code shows an API key or authentication error, and the helper's log shows a Permission denied error from the apiKeyHelper call or the SessionStart hook.

Cause: The helper binary's executable bit isn't set. This is common after an MDM deployment tool copies the binary without keeping POSIX permissions.

Fix: Run chmod 755 on the deployed binary path. See Set executable permissions on macOS and Linux.

Symptom: macOS Gatekeeper blocks the binary with a message that it can't verify the binary, or execution fails with no message.

Cause: Someone downloaded the binary by hand instead of deploying it through the signed PKG installer, so it carries the com.apple.quarantine extended attribute.

Fix: Remove the quarantine attribute, or deploy through the PKG installer instead. See Remove the macOS quarantine attribute.

Symptom: --install stops and lists one or more conflicting environment variables instead of completing.

Cause: A variable such as ANTHROPIC_API_KEY or CLAUDE_CODE_USE_BEDROCK is already set, and it would bypass routing through the Workforce AI Security Gateway.

Fix: Unset the variable, or run install again with --force to have the helper rename it for you. See Resolve environment variable conflicts.

For more information, see:

Claude Code reads its configuration from settings.json, in the .claude directory of your home folder. The path varies by operating system:

The install command writes these settings:

All writes are surgical. The install command adds or updates only the specific keys listed above, and keeps your existing settings.

On Windows, paths must use backslash notation, with each backslash escaped as \\ in JSON:

The compiled binary runs natively on Windows. It needs no additional shell environment, such as Git Bash or WSL.