The Workforce AI Security Gateway and Model Router enables organizations to intercept Claude Code traffic. It redirects inference requests to private models connected to their Workforce AI Security tenant. When configured, Workforce AI Security routes Claude Code requests to a designated private model instead. Otherwise, these requests would go directly to the Anthropic API. This lets organizations apply the same governance controls used for other AI services. It also lets them apply the same policy enforcement.

This feature requires configuration in two places. The first is the Claude Code Model Router settings in the Workforce AI Security admin console. The second is the Claude Code Helper installed on each developer's machine.

Some organizations have deployed Claude models through a cloud provider. Examples include AWS Bedrock, Google Vertex AI, and Azure AI Foundry. These organizations can use this feature to redirect Claude Code traffic to those privately hosted models. This keeps traffic off the public Anthropic API. This gives development teams access to the same Claude Code experience. It also keeps inference traffic within the organization's own cloud environment.

Two common drivers for this are data privacy and cost. Some organizations have strict data residency requirements. Some also have internal policies that restrict sending code and prompts to third-party APIs. These organizations can use the model router to ensure that inference requests stay within their controlled infrastructure. Other organizations have negotiated committed use agreements or reserved capacity with a cloud provider. They can also route Claude Code traffic through those arrangements rather than incurring separate Anthropic API costs.

The Claude Code Model Router is configured at the policy level. Admins can enable it on the Default Policy. They can also enable it on any Group Policy. To access the router settings, navigate to either Default Policy or Group Policies in the GOVERN section. Then scroll to the Claude Code Model Router section.

The router is enabled using the toggle at the top of the Claude Code Model Router section. All three model routes must be configured. Only then can the router function correctly. The three Claude models that require a route are:

Each model route maps a Claude model to a private model. That private model must be available in the organization's Workforce AI Security tenant. The dropdown for each route only shows private models. These models must belong to a compatible model family. Claude Haiku 4.5 supports routing to private models from the Haiku, Sonnet, or Opus family. Claude Sonnet 4.6 and Claude Opus 4.6 each support routing to models from either the Sonnet or Opus family. Using the latest available model versions is recommended. Older models may result in failed requests or degraded outputs.

The selected private model may match the same model family as the Claude model being routed. When it does, a Recommended label appears next to the selection. This label indicates that the routing configuration meets the recommended capability equivalence.

Routing Claude Code traffic through Workforce AI Security requires the Claude Code Helper. This helper must be installed on each developer's machine. The helper is a cross-platform utility distributed as a compiled, zero-dependency binary or as a Node.js script. It handles OAuth 2.0 token-based authentication. It also exports OS-trusted CA certificates so that Claude Code trusts TLS inspection. It also configures all required Claude Code settings during installation.

By default, Claude Code authenticates directly to the Anthropic API using a static API key. Requests may instead be routed through the Workforce AI Security model router. When that happens, Claude Code must use OAuth 2.0 tokens. The organization's Workforce AI Security identity service issues these tokens. The Claude Code Helper replaces the static API key with this token-based flow. Claude Code calls the helper before each session. The helper then returns a valid bearer token. This token is sent with every model request.

The helper implements the OAuth 2.0 Device Authorization Grant flow (RFC 8628). On first use, it contacts the Workforce AI Security authorization server. It then prompts the developer to complete a one-time login in their browser. After authorization, the helper caches access and refresh tokens in the OS-native credential manager. On subsequent sessions, the helper checks the cached token. If the token is approaching expiration (past its midpoint), it proactively refreshes using the stored refresh token. This means sessions are not interrupted. A new browser-based login is only required if both tokens have expired and a final refresh attempt also fails.

Tokens are stored using the OS-native credential manager on each platform. Windows uses Windows Credential Manager, macOS uses Keychain, and Linux uses Secret Service (GNOME Keyring). Credentials are never written to disk as plain text.

The helper is available from Workforce AI Security support as either a compiled binary (no runtime dependencies) or a Node.js script. The script requires Node.js 18 or later. Organizations can distribute it to developer machines through their standard software distribution or MDM process. Alternatively, developers can install it directly using the built-in install command.

The Claude Code Helper requires one of the following:

On Linux, the secret-tool utility must also be installed for credential storage. It is included in the libsecret-tools package:

The helper includes a built-in install command that copies it to a standard location. It also automatically configures ~/.claude/settings.json:

The install command:

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

Before installing, the helper checks for environment variables. It looks for variables that would prevent correct routing through the Workforce AI Security Gateway. If conflicting variables are detected, installation is aborted and the conflicts are listed. Blocked variables include:

To automatically disable detected conflicts, use the --force flag:

This renames each conflicting variable by prefixing it with SP_DISABLE_ in the settings file where it was found. Variables set in the shell environment (not in a settings file) cannot be renamed automatically. A warning is shown with instructions to unset them manually.

To see a full diagnostic of all detected configuration issues without making changes:

The report includes a Permissions Audit section that checks runtime directory ownership and file permissions. This section is particularly useful for diagnosing issues in MDM-deployed environments.

For fully unattended installation (useful in scripts or provisioning workflows):

To remove the helper and revert Claude Code settings:

The uninstall command removes the installed helper and stored credentials from the OS credential manager. It surgically reverts only the settings keys that were written during install. User-added allow rules, other deny entries, and all other env and hooks settings are preserved. Log files, backup files, and the CA certificate file are retained. A timestamped backup of settings.json is created before any changes are made.

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

This forces re-authentication on the next Claude Code session. It preserves the installation, settings, and CA certificates in the process. Useful for troubleshooting authentication issues or switching tenant accounts. The short alias is -cc.

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

The short alias is -cl.

The command creates a zip file on the desktop. The zip file contains filtered log files, the current --report output, and configuration details. Binary files and credentials are excluded. The bundle is suitable for sharing with Workforce AI Security support. Each file in the zip is capped at 10 MB.

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

macOS / Linux:

Windows (run as Administrator):

The short alias is -fp.

This command scans the affected directories, confirms the changes, and corrects ownership. As a result, the current user can write to the required paths.

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

The helper automatically exports OS-trusted CA certificates to ~/.surepath/claude-code-helper/certs/extra-ca-certs.pem at the start of each session via the SessionStart hook. The NODE_EXTRA_CA_CERTS environment variable is set to this path. This lets Claude Code trust certificates installed at the OS level. This includes the Workforce AI Security CA certificate required for TLS inspection.

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

Some organizations handle authentication separately. If they only need the CA certificate configured, they can 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.

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

The following settings are written to ~/.claude/settings.json by the install command:

All writes are surgical. Only the specific keys listed above are added or updated. Existing settings are preserved.

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

The helper runs via Node.js on all platforms. No additional shell environment such as Git Bash or WSL is required on Windows.

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 the pattern:

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

The installer automatically:

This eliminates the need for MDM admins to include separate post-install scripts for permission or quarantine handling. The PKG handles both automatically during installation.

The installer displays as "Workforce AI Security - Claude Code Helper" in the macOS Installer UI. It requires administrator privileges. It installs to the local system domain only (not user home directories).

The macOS binaries and PKG installers distributed by Workforce AI Security are fully signed. They are also notarized for enterprise deployment.

Binary signing: Each macOS binary is signed with a Developer ID Application certificate. It also includes a hardened runtime entitlement. This satisfies macOS Gatekeeper requirements. It also allows the binary to execute without security warnings or manual approval on managed devices.

PKG signing: Each .pkg installer is signed with a Developer ID Installer certificate. MDM platforms such as JAMF, Mosyle, and Kandji can deploy signed PKGs without triggering Gatekeeper blocks. No user intervention is required.

Apple Notarization: Both the signed binaries and the signed PKGs are submitted to Apple's notarization service. After successful notarization, the notarization ticket is stapled to each PKG. This allows offline Gatekeeper verification. The device does not need to contact Apple's servers at install time. This still lets it confirm the package is trusted.

The PKGs are signed and notarized. Because of this, the com.apple.quarantine extended attribute and Gatekeeper blocks described in the manual deployment section do not apply. This is true when using the PKG installer. These issues only affect binaries that are manually downloaded. They also affect binaries deployed outside of a signed package.

To verify the signing and notarization status of a PKG:

To verify Gatekeeper approval:

For enterprise or fleet-wide deployments, the recommended approach is to use a managed-settings.json file. Deploy it alongside the helper binary or script. Claude Code reads this file at startup. It treats the file's values as organization-level defaults. These defaults cannot be overridden by individual user settings.

To deploy via MDM:

Pre-built managed-settings.json files for each supported platform and distribution format are available from Workforce AI Security support.

The macOS PKG installer includes a default managed-settings.json. This file is pre-configured for the standard Workforce AI Security gateway deployment. This default configuration is suitable for most organizations.

Admins may need to customize the managed settings. For example, they might modify permissions, change environment variables, add additional hooks, or point to a different gateway URL. In that case, they have two options:

Install the standard PKG. Then deploy a customized managed-settings.json to /Library/Application Support/ClaudeCode/ using a separate MDM policy. For example, use a JAMF "Copy File" payload or a post-install script. This overwrites the default settings file delivered by the PKG. The signed, notarized binary stays in place.

Use the standalone signed binary from the build artifacts along with a custom managed-settings.json to create a custom PKG. The build artifacts are available separately from Workforce AI Security support. Build it using macOS pkgbuild and productbuild. Example managed-settings.json templates for each platform and architecture are included in the release artifacts under the examples/managed-settings/ directory.

In both cases, the managed-settings.json file must use absolute system paths. The ~ shortcut and %USERPROFILE% expansion are not supported. Refer to the platform-specific example files for the correct path format.

Note: If deploying via the macOS PKG installer, the steps in this section are handled automatically. The package's post-install script handles them. The following guidance applies only when deploying the binary manually (outside of a PKG).

On macOS and Linux, the helper binary must have its executable bit set. Claude Code cannot run it otherwise. MDM deployment tools — including Jamf, Intune, and similar platforms — typically do not preserve POSIX file permissions. This applies when copying or downloading files to managed machines. The binary arrives on the device with default permissions. Those permissions do not include the executable bit. This happens even if the source file was executable.

If the executable bit is not set, Claude Code will fail to call the helper. This failure happens at session start. The apiKeyHelper call and the SessionStart hook will both return a Permission denied error. As a result, developers will be unable to authenticate. This failure is often reported to the developer as an API key or authentication error. There is no obvious indication that the root cause is a file permission issue.

To prevent this, include a chmod command as part of the MDM post-install script or package configuration. Run it immediately after the binary is deployed:

Running chmod in the post-install step ensures the permission is set automatically on every managed machine. This removes the need for manual intervention.

To verify the permission is correctly set on a device, run:

The output should show -rwxr-xr-x at the start of the line. If it shows -rw-r--r-- or similar without the x bits, the binary is not executable.

On macOS, a binary may be downloaded from the internet rather than deployed through a signed package. In that case, it may also 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 via the Workforce AI Security signed and notarized PKG installer do not receive this attribute. Their executable bit is set automatically. The PKG installer is the recommended deployment method for macOS.

Alternatively, the helper may already be distributed to developer machines. In that case, individual developers can run the install command (node claude-code-helper.js -i) themselves. This configures their own ~/.claude/settings.json automatically.

Paths in managed-settings.json must be absolute system-wide paths. The ~ shortcut and %USERPROFILE% expansion are not supported.