Preview: The SurePath AI Claude Code Plugin is currently in early preview. Behavior, configuration, and deployment steps may change before general availability.

The SurePath AI Claude Code Plugin brings Claude Code traffic under SurePath AI governance. It runs a local proxy on each managed machine that Claude Code routes through, forwarding all inference traffic to the SurePath AI gateway. It handles authentication, CA certificate trust, and proxy configuration automatically — Claude Code is launched as normal and governance is applied without any changes to the user's workflow.

Note: This feature requires a SurePath AI tenant and the plugin binary deployed to each managed machine.

Use cases

SurePath AI governs GenAI traffic at the network level, either through SASE forward proxy chaining or PAC-based routing. Most AI tools respect these configurations and their traffic reaches SurePath AI automatically. Claude Code is an exception: it does not honor PAC proxy URLs, so it connects directly to api.anthropic.com and bypasses PAC-based routing entirely.

For organizations using a SASE platform, Claude Code traffic may still be captured and inspected at the network level depending on how the SASE is configured — particularly if TLS interception is applied to all outbound traffic rather than selectively via PAC. For organizations that rely on PAC-based routing to steer GenAI traffic to SurePath AI, there is no way to bring Claude Code under governance without additional tooling on the managed machine. That is what this plugin addresses.

Once Claude Code traffic reaches the SurePath AI gateway, it is subject to the same governance policies that apply to all other AI tools in your organization — access control, content inspection, and full session visibility in User Activity.

How it works

When Claude Code starts, the plugin performs three steps:

Authenticates the user. On first use, a browser window opens for a one-time login using the organization's identity provider. After that, the cached session is reused automatically. Tokens are stored in the OS-native credential manager and refreshed in the background, so sessions are never interrupted by re-authentication.
Starts a local proxy. The plugin launches a PAC-aware proxy on localhost:8888 that forwards Claude Code traffic to the SurePath AI gateway according to the organization's routing rules.
Configures CA certificate trust. The plugin sets the NODE_EXTRA_CA_CERTS environment variable so Claude Code trusts the organization's CA certificates. This prevents TLS inspection from causing certificate errors.

When the session ends, the plugin unregisters and shuts the proxy down if no other sessions are using it. If multiple Claude Code sessions are open at the same time, they share a single proxy instance, so resource use stays low.

Architecture overview

The first Claude Code session to start on a machine launches a local proxy on localhost:8888 and becomes its owner. Subsequent sessions — additional terminal windows, editor integrations, or other Claude Code instances running concurrently — register with the existing proxy rather than starting a new one. All sessions route their traffic through the same proxy process, which forwards it to the SurePath AI gateway.

Ownership of the proxy is tracked dynamically. When the current owner session ends, ownership transfers to another active session automatically. The proxy stays running as long as at least one session is registered. When the last session ends, it tears the proxy down. This means the proxy is never left running unnecessarily in the background and never requires manual management.

Platform requirements

The plugin is a compiled, self-contained binary with no runtime dependencies. It is available for six platform targets:

Platform	Binary name
Windows x64	`surepath-claude-code-plugin-windows-x64.exe`
Windows ARM64	`surepath-claude-code-plugin-windows-arm64.exe`
Linux x64	`surepath-claude-code-plugin-linux-x64`
Linux ARM64	`surepath-claude-code-plugin-linux-arm64`
macOS Intel	`surepath-claude-code-plugin-macos-x64`
macOS Apple Silicon	`surepath-claude-code-plugin-macos-arm64`

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

Debian/Ubuntu: sudo apt install libsecret-tools
Fedora: sudo dnf install libsecret
Arch: sudo pacman -S libsecret

Tokens are stored in the OS-native credential manager and are never written to disk as plain text:

Platform	Credential storage
macOS	Keychain
Windows	Windows Credential Manager
Linux	Secret Service (GNOME Keyring / KWallet)

Deploying via MDM

The recommended deployment method for enterprise environments is to distribute the plugin binary and a managed-settings.json file using your existing MDM, GPO, or configuration management tooling. This approach requires no action from users — Claude Code picks up the configuration automatically at startup, and authentication happens on first launch.

How managed settings work

managed-settings.json is a file Claude Code reads at startup from a system-level directory. Settings in this file are treated as organization-level defaults that cannot be overridden by individual users. The file configures the proxy environment variables, the CA certificate path, and the SessionStart/SessionEnd hooks that call the plugin binary at the start and end of each Claude Code session.

managed-settings.json file locations:

Platform	Path
macOS	`/Library/Application Support/ClaudeCode/managed-settings.json`
Linux / WSL	`/etc/claude-code/managed-settings.json`
Windows	`C:\Program Files\ClaudeCode\managed-settings.json`

Plugin binary locations:

Platform	Path
macOS	`/Library/Application Support/ClaudeCode/surepath/bin/`
Linux	`/opt/surepath/bin/`
Windows	`C:\Program Files\ClaudeCode\surepath\bin\`

CA certificate locations:

Platform	Path
macOS	`/Library/Application Support/ClaudeCode/surepath/certs/`
Linux	`/opt/surepath/certs/`
Windows	`C:\Program Files\ClaudeCode\surepath\certs\`

Example managed-settings.json (macOS Apple Silicon)

{
  "env": {
    "HTTP_PROXY": "http://localhost:8888",
    "HTTPS_PROXY": "http://localhost:8888",
    "http_proxy": "http://localhost:8888",
    "https_proxy": "http://localhost:8888",
    "NODE_EXTRA_CA_CERTS": "/Library/Application Support/ClaudeCode/surepath/certs/surepath-ai-root-ca.pem"
  },
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "\"/Library/Application Support/ClaudeCode/surepath/bin/surepath-claude-code-plugin-macos-arm64\" start" }] }],
    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "\"/Library/Application Support/ClaudeCode/surepath/bin/surepath-claude-code-plugin-macos-arm64\" stop" }] }]
  }
}

Pre-built managed-settings.json templates for each platform and architecture are included in the release artifacts. Per-platform INSTALL.md files are also included in examples/managed-settings/.

macOS (Jamf, Mosyle, or other MDM)

Tip: For macOS deployments, use the pre-built signed and notarized .pkg installer where possible — see macOS PKG installer below. The steps below apply when deploying the binary directly without a PKG.

TARGET_DIR="/Library/Application Support/ClaudeCode"
BIN_DIR="$TARGET_DIR/surepath/bin"
CERT_DIR="$TARGET_DIR/surepath/certs"sudo mkdir -p "$TARGET_DIR" "$BIN_DIR" "$CERT_DIR"sudo cp surepath-claude-code-plugin-macos-arm64 "$BIN_DIR/"
sudo cp surepath-ai-root-ca.pem "$CERT_DIR/"
sudo cp managed-settings.json "$TARGET_DIR/"sudo chmod 755 "$BIN_DIR/surepath-claude-code-plugin-macos-arm64"
sudo chmod 644 "$CERT_DIR/surepath-ai-root-ca.pem"
sudo chmod 644 "$TARGET_DIR/managed-settings.json"

Windows (Intune, SCCM, or GPO)

$targetDir = "C:\Program Files\ClaudeCode"
$binDir = "$targetDir\surepath\bin"
$certDir = "$targetDir\surepath\certs"New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
New-Item -ItemType Directory -Path $binDir -Force | Out-Null
New-Item -ItemType Directory -Path $certDir -Force | Out-NullCopy-Item "surepath-claude-code-plugin-windows-x64.exe" "$binDir\" -Force
Copy-Item "surepath-ai-root-ca.pem" "$certDir\" -Force
Copy-Item "managed-settings.json" "$targetDir\" -Force

Linux (Ansible, Puppet, or Chef)

TARGET_DIR="/etc/claude-code"
BIN_DIR="/opt/surepath/bin"
CERT_DIR="/opt/surepath/certs"sudo mkdir -p "$TARGET_DIR" "$BIN_DIR" "$CERT_DIR"sudo cp surepath-claude-code-plugin-linux-x64 "$BIN_DIR/"
sudo cp surepath-ai-root-ca.pem "$CERT_DIR/"
sudo cp managed-settings.json "$TARGET_DIR/"sudo chmod 755 "$BIN_DIR/surepath-claude-code-plugin-linux-x64"
sudo chmod 644 "$CERT_DIR/surepath-ai-root-ca.pem"
sudo chmod 644 "$TARGET_DIR/managed-settings.json"

Important (macOS and Linux): MDM tools — including Jamf, Intune, and similar platforms — typically do not preserve POSIX file permissions when deploying files. The binary will arrive without its executable bit set, which causes Claude Code to report a Permission denied error at session start. Always include a chmod 755 step in the post-install script.

First launch

Once the files are deployed, users launch Claude Code as normal (claude). On first launch:

A browser window opens for a one-time sign-in. The code displayed in the terminal is entered to complete device authorization.
The local proxy starts on localhost:8888.
All Claude Code traffic routes through the SurePath AI gateway.

No terminal restart, no manual configuration, and no prompts requiring IT involvement are needed.

macOS PKG installer

For macOS deployments, SurePath AI provides pre-built .pkg installer packages for both Apple Silicon and Intel. The PKG is the recommended deployment method for macOS — it handles binary permissions, quarantine removal, and managed settings in a single step with no post-install scripting required.

Installer filenames follow the pattern:

surepath-claude-code-plugin-<version>-macos-arm64.pkg
surepath-claude-code-plugin-<version>-macos-x64.pkg

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

File	Install path	Purpose
Binary	`/Library/Application Support/ClaudeCode/surepath/bin/surepath-claude-code-plugin-macos-<arch>`	The compiled plugin binary
Configuration	`/Library/Application Support/ClaudeCode/managed-settings.json`	Managed settings for Claude Code

The PKG's post-install script automatically:

Sets the binary as executable (chmod 755)
Removes the com.apple.quarantine extended attribute from the binary
Sets appropriate permissions on managed-settings.json (chmod 644)

A pre-install script removes any existing managed-settings.json before copying the new one, preventing upgrade conflicts.

The installer displays as "SurePath AI - Claude Code Plugin" in the macOS Installer UI and requires administrator privileges. It installs to the local system domain — not to user home directories.

Customizing managed settings

The PKG ships with a default managed-settings.json that works for most organizations. If you need to customize it — for example to modify permissions, add hooks, or change environment variables — you have two options:

Option 1: Deploy a replacement after installation. Install the standard PKG, then use a separate MDM policy to deploy a customized managed-settings.json to /Library/Application Support/ClaudeCode/. This overwrites the default file while keeping the signed, notarized binary in place.

Option 2: Build a custom PKG. Use the standalone signed binary together with your own managed-settings.json to build a custom package using pkgbuild and productbuild. Example templates for each platform are included in the release artifacts under examples/managed-settings/.

In both cases, paths in managed-settings.json must be absolute system paths. The ~ shortcut and %USERPROFILE% expansion are not supported.

Code signing and notarization (macOS)

The macOS binaries and PKG installers are fully signed and notarized for enterprise deployment:

Binary signing: Each 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 run on managed devices without security warnings or manual approval.
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 signed PKGs are submitted to Apple's notarization service. After successful notarization, the ticket is stapled to each PKG, allowing offline Gatekeeper verification — the device does not need to contact Apple's servers at install time.

To verify signing and notarization status:

pkgutil --check-signature /path/to/surepath-claude-code-plugin-<version>-macos-<arch>.pkg# Verify Gatekeeper approval
spctl -a -t install -vv /path/to/surepath-claude-code-plugin-<version>-macos-<arch>.pkg

Diagnostic commands

--report / -r

Prints a diagnostic report covering installation state, file permissions, proxy health, gateway connectivity, credential state, and recent log output:

surepath-claude-code-plugin --report

--collect-logs / -cl

Bundles diagnostic data into a timestamped zip on the Desktop for sharing with SurePath AI support. Includes logs, configuration files, proxy status, and a snapshot of the --report output. Credentials and binaries are automatically excluded:

surepath-claude-code-plugin --collect-logs

--fix-permissions / -fp

Detects and repairs file ownership issues caused by a previous admin deployment. Scans ~/.surepath/claude-code-plugin/ and ~/.claude/ for root-owned files and corrects ownership so the current user can write to the required paths:

# macOS/Linux — requires sudo
sudo surepath-claude-code-plugin --fix-permissions# Windows — run as Administrator
surepath-claude-code-plugin --fix-permissions

The --install, --uninstall, and --clear-credentials commands are blocked when run as root or Administrator. Use --fix-permissions with elevation only for the repair step; run all other commands as the target user.

Clearing credentials

To delete stored credentials without performing a full uninstall:

surepath-claude-code-plugin --clear-credentials

Alias: -cc

This forces re-authentication on the next Claude Code session while preserving all other configuration, settings, and CA certificates. Use this when troubleshooting authentication issues or when switching tenant accounts.

Manual credential removal:

# macOS
security delete-generic-password -s surepath-ai-claude-code-plugin -a session# Windows (PowerShell)
cmdkey /delete:surepath-ai-claude-code-plugin# Linux
secret-tool clear service surepath-ai-claude-code-plugin account session

Uninstalling

To remove the plugin from a managed deployment, stop any running proxy processes and delete the deployed files from the system directories.

macOS:

pkill -f "surepath-claude-code-plugin" || truesudo rm -f "/Library/Application Support/ClaudeCode/surepath/bin/surepath-claude-code-plugin-macos-arm64"
sudo rm -f "/Library/Application Support/ClaudeCode/managed-settings.json"
sudo rm -f "/Library/Application Support/ClaudeCode/surepath/certs/surepath-ai-root-ca.pem"rm -rf ~/.surepath/claude-code-plugin/security delete-generic-password -s surepath-ai-claude-code-plugin -a session 2>/dev/null || true

Troubleshooting

Check logs

Logs are written to ~/.surepath/claude-code-plugin/logs/ on all platforms. Files use daily naming with same-day rollover after 10 MB:

Base file: <component>-YYYY-MM-DD.log
Rollover: <component>-YYYY-MM-DD.1.log, .2.log, etc.

Enable debug logging

# macOS/Linux
export SUREPATH_LOG_LEVEL=debug
claude# Windows (PowerShell)
$env:SUREPATH_LOG_LEVEL = "debug"
claude

Check proxy status

# Health check
curl http://localhost:8888/health# View proxy status file
cat ~/.surepath/claude-code-plugin/proxy-status.json

Common issues

Proxy not starting

Check logs in ~/.surepath/claude-code-plugin/logs/. Verify port 8888 is not in use by another application.

401 errors persist

Run surepath-claude-code-plugin --clear-credentials to force re-authentication. Run surepath-claude-code-plugin --report to check token state and gateway connectivity.

Certificate errors

Verify NODE_EXTRA_CA_CERTS is set correctly in managed-settings.json and that the CA certificate file exists at the configured path. Re-deploying the files and restarting Claude Code will re-apply the configuration.

Permission denied at session start (macOS/Linux)

The binary was deployed without the executable bit set, which is common with MDM tools. Run sudo surepath-claude-code-plugin --fix-permissions, or re-deploy with chmod 755 in the post-install script.

Managed settings not loading

Verify the managed-settings.json file exists in the correct system path — not in a user home directory. Check that the file is readable by all users and that the JSON is valid: python -m json.tool managed-settings.json.

Platform support summary

Feature	Windows	macOS	Linux
Managed settings deployment	Yes	Yes	Yes
`NODE_EXTRA_CA_CERTS`	Yes	Yes	Yes
PAC-based proxy routing	Yes	Yes	Yes
Device authentication	Yes	Yes	Yes
Shared proxy across sessions	Yes	Yes	Yes
Secure token storage	Credential Manager	Keychain	Secret Service
PKG installer	N/A	Yes	N/A
Signed and notarized	N/A	Yes	N/A

Intercepting Claude Code traffic in Proxy PAC deployments (Preview)