# Tanium Distribution

Deploy Capsule Security hooks for AI coding assistants across your fleet using Tanium. This guide covers deployment for Cursor, Devin (Windsurf), GitHub Copilot, Claude Code, and Codex on both Windows and macOS using Tanium Deploy packages.

## Prerequisites

- Access to the **Tanium Console** with administrative privileges
- **Tanium Deploy** module enabled
- A **Capsule Security** account with admin access
- Target endpoints managed by Tanium


## Cursor

Deploy the Cursor hooks configuration using a Tanium Deploy package.

### Step 1: Download the Configuration

1. Log in to the **Capsule Security** portal
2. Navigate to **Settings > Integrations**
3. Locate the **Cursor** integration
4. Download the `hooks.json` file


### Windows Deployment

1. Log in to the **Tanium Console**
2. Navigate to **Tanium Deploy > Packages**
3. Click **Create Package** and configure:
  - **Name**: Capsule Security – Cursor Hooks (Windows)
  - **Description**: Deploys Capsule Security hooks configuration for Cursor
4. Upload the `hooks.json` file to the package files
5. Set the **Command** to run the following script:

```cmd
cmd.exe /c mkdir "C:\ProgramData\Cursor" & copy /Y "hooks.json" "C:\ProgramData\Cursor\hooks.json"
```
6. Create a **Deployment**:
  - Navigate to **Tanium Deploy > Deployments**
  - Click **Create Deployment**
  - Select the **Capsule Security – Cursor Hooks (Windows)** package
  - Target the appropriate **Computer Groups** or use a Tanium question to filter endpoints
  - Configure the schedule:
    - **Type**: Single or Recurring
    - **Restart required**: No
  - Deploy


### macOS Deployment

1. Navigate to **Tanium Deploy > Packages**
2. Click **Create Package** and configure:
  - **Name**: Capsule Security – Cursor Hooks (macOS)
  - **Description**: Deploys Capsule Security hooks configuration for Cursor on macOS
3. Upload the `hooks.json` file to the package files
4. Set the **Command** to run the following script:

```bash
#!/bin/bash
HOOKS_DIR="/Library/Application Support/Cursor"
mkdir -p "$HOOKS_DIR"
cp hooks.json "$HOOKS_DIR/hooks.json"
chmod 644 "$HOOKS_DIR/hooks.json"
exit 0
```
5. Create a **Deployment** targeting macOS endpoints using the appropriate Computer Groups


### Verification

After deployment, restart Cursor on target devices, then:

1. Open Cursor Settings
2. Navigate to the **Hooks** tab
3. Confirm the hooks are listed and enabled


## Devin (Windsurf)

Deploy the Devin (Windsurf) hooks configuration using a Tanium Deploy package. Cascade merges hook configurations from the system, user, and workspace levels ([Cascade hooks documentation](https://docs.devin.ai/desktop/cascade/hooks)), so deploying to the system-level path applies the Capsule hooks to every user on the device, and they cannot be disabled by end users.

### Step 1: Download the Configuration

1. Log in to the **Capsule Security** portal
2. Navigate to **Settings > Integrations**
3. Locate the **Devin (Windsurf)** integration
4. Choose **MDM** as the deployment method
5. For Windows endpoints, select **Windows** and extract the downloaded `capsule-windsurf-managed.zip` (contains `hooks.json` and the `CapsuleWindsurfHook.ps1` companion script)
6. For macOS endpoints, select **Mac** and download the `hooks.json` file


### Windows Deployment

1. Log in to the **Tanium Console**
2. Navigate to **Tanium Deploy > Packages**
3. Click **Create Package** and configure:
  - **Name**: Capsule Security – Devin (Windsurf) Hooks (Windows)
  - **Description**: Deploys Capsule Security hooks configuration for Devin (Windsurf)
4. Upload the `hooks.json` and `CapsuleWindsurfHook.ps1` files to the package files
5. Set the **Command** to run the following script:

```cmd
cmd.exe /c mkdir "C:\ProgramData\Windsurf" & mkdir "C:\ProgramData\Capsule\WindsurfHooks" & copy /Y "hooks.json" "C:\ProgramData\Windsurf\hooks.json" & copy /Y "CapsuleWindsurfHook.ps1" "C:\ProgramData\Capsule\WindsurfHooks\CapsuleWindsurfHook.ps1"
```
> The `hooks.json` invokes the companion script from `C:\ProgramData\Capsule\WindsurfHooks\`, so both files must be deployed
6. Create a **Deployment**:
  - Navigate to **Tanium Deploy > Deployments**
  - Click **Create Deployment**
  - Select the **Capsule Security – Devin (Windsurf) Hooks (Windows)** package
  - Target the appropriate **Computer Groups** or use a Tanium question to filter endpoints
  - Configure the schedule:
    - **Type**: Single or Recurring
    - **Restart required**: No
  - Deploy


### macOS Deployment

1. Navigate to **Tanium Deploy > Packages**
2. Click **Create Package** and configure:
  - **Name**: Capsule Security – Devin (Windsurf) Hooks (macOS)
  - **Description**: Deploys Capsule Security hooks configuration for Devin (Windsurf) on macOS
3. Upload the `hooks.json` file to the package files
4. Set the **Command** to run the following script:

```bash
#!/bin/bash
HOOKS_DIR="/Library/Application Support/Windsurf"
mkdir -p "$HOOKS_DIR"
cp hooks.json "$HOOKS_DIR/hooks.json"
chmod 644 "$HOOKS_DIR/hooks.json"
exit 0
```
5. Create a **Deployment** targeting macOS endpoints using the appropriate Computer Groups


### Verification

Hooks are loaded at application start, so after deployment, close Devin Desktop completely on target devices and reopen it, then:

1. Start a **Cascade** session and run a simple task to generate activity
2. In the Capsule portal, navigate to **Inventory > Agents** and confirm the agent appears


## GitHub Copilot

Deploy the GitHub Copilot hooks configuration using a Tanium Deploy package.

### Step 1: Download the Configuration

1. Log in to the **Capsule Security** portal
2. Navigate to **Settings > Integrations**
3. Locate the **GitHub Copilot** integration
4. Download the `capsule-hooks.json` file


### Windows Deployment

1. Log in to the **Tanium Console**
2. Navigate to **Tanium Deploy > Packages**
3. Click **Create Package** and configure:
  - **Name**: Capsule Security – GitHub Copilot Hooks (Windows)
  - **Description**: Deploys Capsule Security hooks configuration for GitHub Copilot in VS Code
4. Upload the `capsule-hooks.json` file to the package files
5. Set the **Command** to run the following PowerShell script:

```powershell
$userProfiles = Get-ChildItem "C:\Users" -Directory | Where-Object { $_.Name -notin @('Public', 'Default', 'Default User') }

foreach ($profile in $userProfiles) {
    $hooksDir = Join-Path $profile.FullName "AppData\Roaming\Code\User\hooks"
    if (-not (Test-Path $hooksDir)) {
        New-Item -ItemType Directory -Path $hooksDir -Force | Out-Null
    }
    Copy-Item -Path "capsule-hooks.json" -Destination "$hooksDir\capsule-hooks.json" -Force
}

Write-Output "Capsule hooks configuration deployed successfully."
exit 0
```
6. Create a **Deployment**:
  - Navigate to **Tanium Deploy > Deployments**
  - Click **Create Deployment**
  - Select the **Capsule Security – GitHub Copilot Hooks (Windows)** package
  - Target the appropriate **Computer Groups**
  - Deploy


### macOS Deployment

1. Navigate to **Tanium Deploy > Packages**
2. Click **Create Package** and configure:
  - **Name**: Capsule Security – GitHub Copilot Hooks (macOS)
  - **Description**: Deploys Capsule Security hooks configuration for GitHub Copilot on macOS
3. Upload the `capsule-hooks.json` file to the package files
4. Set the **Command** to run the following script:

```bash
#!/bin/bash
for USER_HOME in /Users/*/; do
    USERNAME=$(basename "$USER_HOME")
    if [ "$USERNAME" = "Shared" ] || [ "$USERNAME" = ".localized" ]; then
        continue
    fi
    HOOKS_DIR="$USER_HOME/Library/Application Support/Code/User/hooks"
    mkdir -p "$HOOKS_DIR"
    cp capsule-hooks.json "$HOOKS_DIR/capsule-hooks.json"
    chmod 644 "$HOOKS_DIR/capsule-hooks.json"
    chown "$USERNAME" "$HOOKS_DIR/capsule-hooks.json"
done
exit 0
```
5. Create a **Deployment** targeting macOS endpoints using the appropriate Computer Groups


### Verification

After deployment, restart VS Code on target devices, then:

1. Right-click in the **Chat** view and select **Diagnostics**
2. Confirm the hooks are loaded and enabled


## Claude Code

Deploy the Claude Code managed settings configuration using a Tanium Deploy package.

### Step 1: Download the Configuration

1. Log in to the **Capsule Security** portal
2. Navigate to **Settings > Integrations**
3. Locate the **Claude Code** integration
4. Click **Install** and select your target platform
5. Download the `managed-settings.json` file


### Windows Deployment

1. Log in to the **Tanium Console**
2. Navigate to **Tanium Deploy > Packages**
3. Click **Create Package** and configure:
  - **Name**: Capsule Security – Claude Code Hooks (Windows)
  - **Description**: Deploys Capsule Security managed settings for Claude Code
4. Upload the `managed-settings.json` file to the package files
5. Set the **Command** to run the following script:

```cmd
cmd.exe /c mkdir "C:\Program Files\ClaudeCode" & copy /Y "managed-settings.json" "C:\Program Files\ClaudeCode\managed-settings.json"
```
6. Create a **Deployment**:
  - Navigate to **Tanium Deploy > Deployments**
  - Click **Create Deployment**
  - Select the **Capsule Security – Claude Code Hooks (Windows)** package
  - Target the appropriate **Computer Groups**
  - Deploy


### macOS Deployment

1. Navigate to **Tanium Deploy > Packages**
2. Click **Create Package** and configure:
  - **Name**: Capsule Security – Claude Code Hooks (macOS)
  - **Description**: Deploys Capsule Security managed settings for Claude Code on macOS
3. Upload the `managed-settings.json` file to the package files
4. Set the **Command** to run the following script:

```bash
#!/bin/bash
SETTINGS_DIR="/Library/Application Support/ClaudeCode"
mkdir -p "$SETTINGS_DIR"
cp managed-settings.json "$SETTINGS_DIR/managed-settings.json"
chmod 644 "$SETTINGS_DIR/managed-settings.json"
exit 0
```
5. Create a **Deployment** targeting macOS endpoints using the appropriate Computer Groups


### Verification

After deployment, restart Claude Code on target devices, then:

1. Run `/hooks` in Claude Code to confirm all hooks are listed
2. Start a session and verify events appear in the Capsule Security portal


## Codex

Deploy the Codex [managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration) using a Tanium Deploy package. Codex reads a managed `requirements.toml` from `/etc/codex/requirements.toml` (macOS) or `%ProgramData%\OpenAI\Codex\requirements.toml` (Windows); because the configuration is managed, the Capsule hooks are trusted by policy, apply to every user on the device (including users created later), and cannot be overridden or removed by users. No per-user trust approval is required.

### Step 1: Download the Configuration

1. Log in to the **Capsule Security** portal
2. Navigate to **Settings > Integrations**
3. Locate the **Codex** integration
4. Choose **MDM** as the deployment method
5. For Windows endpoints, select **Windows** and extract the downloaded `capsule-codex-managed.zip` (contains `requirements.toml` and the `CapsuleCodexHook.ps1` companion script)
6. For macOS endpoints, select **Mac** and download the `requirements.toml` file


### Windows Deployment

1. Log in to the **Tanium Console**
2. Navigate to **Tanium Deploy > Packages**
3. Click **Create Package** and configure:
  - **Name**: Capsule Security – Codex Managed Configuration (Windows)
  - **Description**: Deploys the Capsule Security managed configuration for Codex
4. Upload the `requirements.toml` and `CapsuleCodexHook.ps1` files to the package files
5. Set the **Command** to run the following script:

```cmd
cmd.exe /c mkdir "C:\ProgramData\OpenAI\Codex" & mkdir "C:\ProgramData\Capsule\CodexHooks" & copy /Y "requirements.toml" "C:\ProgramData\OpenAI\Codex\requirements.toml" & copy /Y "CapsuleCodexHook.ps1" "C:\ProgramData\Capsule\CodexHooks\CapsuleCodexHook.ps1"
```
> The managed configuration invokes the companion script from `C:\ProgramData\Capsule\CodexHooks\`, so both files must be deployed
6. Create a **Deployment**:
  - Navigate to **Tanium Deploy > Deployments**
  - Click **Create Deployment**
  - Select the **Capsule Security – Codex Managed Configuration (Windows)** package
  - Target the appropriate **Computer Groups**
  - Deploy


### macOS Deployment

1. Navigate to **Tanium Deploy > Packages**
2. Click **Create Package** and configure:
  - **Name**: Capsule Security – Codex Managed Configuration (macOS)
  - **Description**: Deploys the Capsule Security managed configuration for Codex on macOS
3. Upload the `requirements.toml` file to the package files
4. Set the **Command** to run the following script:

```bash
#!/bin/bash
CODEX_DIR="/etc/codex"
mkdir -p "$CODEX_DIR"
cp requirements.toml "$CODEX_DIR/requirements.toml"
chmod 644 "$CODEX_DIR/requirements.toml"
exit 0
```
5. Create a **Deployment** targeting macOS endpoints using the appropriate Computer Groups


### Verification

After deployment, close any running Codex CLI sessions on target devices, then:

1. Start a new Codex CLI session so the managed configuration is loaded
2. In the Capsule portal, navigate to **Inventory > Agents** and confirm the Codex agent appears


## Monitoring Deployments

After deploying packages, monitor status in the Tanium Console:

1. Navigate to **Tanium Deploy > Deployments**
2. Select the relevant deployment
3. Review the deployment status:
  - **Complete**: Configuration successfully deployed
  - **Pending**: Deployment waiting for endpoint check-in
  - **Failed**: Review error details and retry


You can also use **Tanium Interact** to ask questions across your fleet to verify deployment:

- Windows (Cursor): `Get File Exists[C:\ProgramData\Cursor\hooks.json] from all machines`
- Windows (Devin (Windsurf)): `Get File Exists[C:\ProgramData\Windsurf\hooks.json] from all machines`
- Windows (Claude Code): `Get File Exists[C:\Program Files\ClaudeCode\managed-settings.json] from all machines`
- Windows (Codex): `Get File Exists[C:\ProgramData\OpenAI\Codex\requirements.toml] from all machines`
- macOS (Cursor): `Get File Exists[/Library/Application Support/Cursor/hooks.json] from all machines`
- macOS (Devin (Windsurf)): `Get File Exists[/Library/Application Support/Windsurf/hooks.json] from all machines`
- macOS (Claude Code): `Get File Exists[/Library/Application Support/ClaudeCode/managed-settings.json] from all machines`
- macOS (Codex): `Get File Exists[/etc/codex/requirements.toml] from all machines`


## Key Considerations

- Tanium packages run as SYSTEM (Windows) or root (macOS) by default
- **Cursor**, **Devin (Windsurf)**, **Claude Code**, and **Codex** use system-level paths - deploy to **Device** computer groups
- **GitHub Copilot** uses user-level paths - the deployment scripts iterate over all user profiles to cover each user on the endpoint; use a recurring deployment schedule to cover users created later
- **Codex** uses a managed configuration (`requirements.toml`) enforced by policy - it applies to all users on the device (including users created later) and cannot be overridden by user-level configuration
- **Devin (Windsurf)** merges system, user, and workspace hook configurations, so the system-level deployment coexists with any per-user hooks and cannot be disabled by end users
- For GitHub Copilot CLI users, create an additional package targeting `%USERPROFILE%\.copilot\hooks\capsule-hooks.json` (Windows) or `~/.copilot/hooks/capsule-hooks.json` (macOS)
- Use Tanium Computer Groups or saved questions to target specific OS versions or departments
- All five integrations can be deployed as separate packages and assigned independently
- For recurring enforcement, configure deployments with a recurring schedule


## Support

For help with deployment:

- **Email**: support@capsule.security
- **Include**: Your organization ID, Tanium environment details, and any error messages


## References

- [Tanium Deploy User Guide](https://docs.tanium.com/deploy/deploy/index.html)
- [Codex Hooks](https://developers.openai.com/codex/hooks)
- [Codex Managed Configuration](https://developers.openai.com/codex/enterprise/managed-configuration)