This feature is currently in early preview. Behavior, configuration steps, and tooling may change before general availability.

The SurePath AI Gateway and Model Router enables organizations to intercept Claude Code traffic and redirect inference requests to private models connected to their SurePath AI tenant. When configured, Claude Code requests that would otherwise go directly to the Anthropic API are routed through the SurePath AI platform to a designated private model, allowing organizations to apply the same governance controls and policy enforcement used for other AI services.

This feature requires configuration in two places: the Claude Code Model Router settings in the SurePath AI admin console, and the Claude Code Helper installed on each developer's machine.

Organizations that have deployed Claude models through a cloud provider — such as AWS Bedrock, Google Vertex AI, or Azure AI Foundry — can use this feature to redirect Claude Code traffic to those privately hosted models instead of the public Anthropic API. This gives development teams access to the same Claude Code experience while keeping inference traffic within the organization's own cloud environment.

Two common drivers for this are data privacy and cost. Organizations with strict data residency requirements or internal policies that restrict sending code and prompts to third-party APIs can use the model router to ensure that inference requests stay within their controlled infrastructure. Organizations that have negotiated committed use agreements or reserved capacity with a cloud provider 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 or 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 before the router can function correctly. The three Claude models that require a route are:

Each model route maps a Claude model to a private model available in the organization's SurePath AI tenant. The dropdown for each route only shows private models that 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, as older models may result in failed requests or degraded outputs.

When the selected private model matches the same model family as the Claude model being routed, 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 SurePath AI requires the Claude Code Helper 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, exports OS-trusted CA certificates so that Claude Code trusts TLS inspection, and configures all required Claude Code settings during installation.

By default, Claude Code authenticates directly to the Anthropic API using a static API key. When requests are routed through the SurePath AI model router, Claude Code must instead use OAuth 2.0 tokens issued by the organization's SurePath AI identity service. The Claude Code Helper replaces the static API key with this token-based flow: Claude Code calls the helper before each session, and the helper returns a valid bearer token that 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 SurePath AI authorization server and 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 so that 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 Credential Manager on Windows, Keychain on macOS, and Secret Service (GNOME Keyring) on Linux. Credentials are never written to disk as plain text.

The helper is available from SurePath AI support as either a compiled binary (no runtime dependencies) or a Node.js script requiring Node.js 18 or later. Organizations can distribute it to developer machines through their standard software distribution or MDM process, or 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 and 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 that would prevent correct routing through the SurePath AI 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, which 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 while preserving the installation, settings, and CA certificates. 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 containing filtered log files, the current --report output, and configuration details. Binary files and credentials are excluded. The bundle is suitable for sharing with SurePath AI support. Each file in the zip is capped at 10 MB.

If the helper reports a permission error when writing certificates or credentials — which can occur after MDM deployment when runtime directories were created by an administrator account — 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 so 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 so that Claude Code trusts certificates installed at the OS level — including the SurePath AI CA certificate required for TLS inspection.

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

Organizations that handle authentication separately and only need the CA certificate configured 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, SurePath AI provides pre-built .pkg installer packages for 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 "SurePath AI - Claude Code Helper" in the macOS Installer UI and requires administrator privileges. It installs to the local system domain only (not user home directories).

The macOS binaries and PKG installers distributed by SurePath AI are fully signed and notarized for enterprise deployment.

Binary signing: Each macOS binary is signed with a Developer ID Application certificate and includes a hardened runtime entitlement. This satisfies macOS Gatekeeper requirements and 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 or requiring user intervention.

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 to confirm the package is trusted.

Because the PKGs are signed and notarized, the com.apple.quarantine extended attribute and Gatekeeper blocks described in the manual deployment section do not apply when using the PKG installer. These issues only affect binaries that are manually downloaded or 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 alongside the helper binary or script. Claude Code reads this file at startup and treats its values as organization-level defaults that 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 SurePath AI support.

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

Admins who need to customize the managed settings — for example, to modify permissions, change environment variables, add additional hooks, or point to a different gateway URL — 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, a JAMF "Copy File" payload or a post-install script). This overwrites the default settings file delivered by the PKG while keeping the signed, notarized binary in place.

Use the standalone signed binary from the build artifacts (available separately from SurePath AI support) along with a custom managed-settings.json to create a custom PKG 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 by the package's post-install script. 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 before Claude Code can run it. MDM deployment tools — including Jamf, Intune, and similar platforms — typically do not preserve POSIX file permissions when copying or downloading files to managed machines. The binary arrives on the device with default permissions that do not include the executable bit, even if the source file was executable.

If the executable bit is not set, Claude Code will fail to call the helper at session start. The apiKeyHelper call and the SessionStart hook will both return a Permission denied error, and developers will be unable to authenticate. This failure is often reported to the developer as an API key or authentication error with 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 immediately after the binary is deployed:

Running chmod in the post-install step ensures the permission is set automatically on every managed machine without requiring 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, if the binary was downloaded from the internet rather than deployed through a signed package, it may also carry a quarantine extended attribute (com.apple.quarantine) that Gatekeeper uses to block execution. This is separate from file permissions. To check for and remove the attribute:

Binaries deployed via the SurePath AI signed and notarized PKG installer do not receive this attribute, and the executable bit is set automatically. The PKG installer is the recommended deployment method for macOS.

Alternatively, once the helper has been distributed to developer machines, individual developers can run the install command (node claude-code-helper.js -i) to configure 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.