# JumpCloud Distribution (macOS)

Deploy Capsule Security hooks for AI coding assistants across your macOS fleet using JumpCloud. This guide covers deployment for Cursor, GitHub Copilot, Claude Code, and Codex using JumpCloud **Commands**, which run a shell script as `root` on bound devices.

## Prerequisites

- A **JumpCloud** administrator account
- The **JumpCloud agent** installed on target devices
- A **Capsule Security** account with admin access
- Target devices running macOS


## Cursor

Deploy the Cursor hooks configuration using a JumpCloud Command.

### 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


### Step 2: Create the Command

1. Log in to the **JumpCloud Admin Portal**
2. Navigate to **DEVICE MANAGEMENT > Commands**
3. Click **(+)** and select **Command**
4. On the **Details** tab, configure the command:
  - **Name**: Deploy Capsule Security Cursor Hooks
  - **Type**: **Mac**
  - **Run As user**: **root** (required for the system-wide path below)
5. Paste the following into the **Command** field, replacing the placeholder line with the contents of the downloaded `hooks.json` (keep the `CAPSULE_HOOKS_EOF` marker lines unchanged and unindented):

```bash
#!/bin/bash
HOOKS_DIR="/Library/Application Support/Cursor"
mkdir -p "$HOOKS_DIR"
chmod 755 "$HOOKS_DIR"
cat > "$HOOKS_DIR/hooks.json" << 'CAPSULE_HOOKS_EOF'
<PASTE YOUR HOOKS.JSON CONTENT HERE>
CAPSULE_HOOKS_EOF
chmod 644 "$HOOKS_DIR/hooks.json"
exit 0
```


### Step 3: Bind and Run

1. Select the **Device Groups** tab (or the **Devices** tab) and bind the target device groups or devices
2. Click **Save**
3. On the **Commands** page, click **Run Now** to execute the command, or configure a schedule so it re-runs on the bound devices
4. Review the **Results** tab to confirm the command completed successfully


### Verification

After the command reports success, restart Cursor on target devices, then:

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


## GitHub Copilot

Deploy the GitHub Copilot hooks configuration using a JumpCloud Command. VS Code reads Copilot hooks from each user's `~/Library/Application Support/Code/User/hooks/` directory rather than a system-wide path, so the command runs as root and writes the configuration into every user profile on the device.

### 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 `hooks.json` file


### Step 2: Create the Command

1. Log in to the **JumpCloud Admin Portal**
2. Navigate to **DEVICE MANAGEMENT > Commands**
3. Click **(+)** and select **Command**
4. On the **Details** tab, configure the command:
  - **Name**: Deploy Capsule Security GitHub Copilot Hooks
  - **Type**: **Mac**
  - **Run As user**: **root** (required to write into each user's home directory below)
5. Paste the following into the **Command** field, replacing the placeholder line with the contents of the downloaded `hooks.json` (keep the `CAPSULE_HOOKS_EOF` marker lines unchanged and unindented):

```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"
    cat > "$HOOKS_DIR/hooks.json" << 'CAPSULE_HOOKS_EOF'
<PASTE YOUR HOOKS.JSON CONTENT HERE>
CAPSULE_HOOKS_EOF
    chmod 644 "$HOOKS_DIR/hooks.json"
    chown "$USERNAME" "$HOOKS_DIR" "$HOOKS_DIR/hooks.json"
done
exit 0
```


### Step 3: Bind and Run

1. Select the **Device Groups** tab (or the **Devices** tab) and bind the target device groups or devices
2. Click **Save**
3. On the **Commands** page, click **Run Now** to execute the command, or configure a schedule so it re-runs to cover users created later
4. Review the **Results** tab to confirm the command completed successfully


### Verification

After the command reports success, 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 JumpCloud Command.

### 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 **macOS** as the target platform
5. Download the `managed-settings.json` file


### Step 2: Create the Command

1. Log in to the **JumpCloud Admin Portal**
2. Navigate to **DEVICE MANAGEMENT > Commands**
3. Click **(+)** and select **Command**
4. On the **Details** tab, configure the command:
  - **Name**: Deploy Capsule Security Claude Code Hooks
  - **Type**: **Mac**
  - **Run As user**: **root** (required for the system-wide path below)
5. Paste the following into the **Command** field, replacing the placeholder line with the contents of the downloaded `managed-settings.json` (keep the `CAPSULE_HOOKS_EOF` marker lines unchanged and unindented):

```bash
#!/bin/bash
SETTINGS_DIR="/Library/Application Support/ClaudeCode"
mkdir -p "$SETTINGS_DIR"
chmod 755 "$SETTINGS_DIR"
cat > "$SETTINGS_DIR/managed-settings.json" << 'CAPSULE_HOOKS_EOF'
<PASTE YOUR MANAGED-SETTINGS.JSON CONTENT HERE>
CAPSULE_HOOKS_EOF
chmod 644 "$SETTINGS_DIR/managed-settings.json"
exit 0
```


### Step 3: Bind and Run

1. Select the **Device Groups** tab (or the **Devices** tab) and bind the target device groups or devices
2. Click **Save**
3. On the **Commands** page, click **Run Now** to execute the command, or configure a schedule so it re-runs on the bound devices
4. Review the **Results** tab to confirm the command completed successfully


### Verification

After the command reports success, 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 CLI hooks configuration using a JumpCloud Command. Codex reads hooks from each user's `~/.codex/hooks.json` rather than a system-wide path, so the command runs as root and writes the configuration into every user profile on the device.

For organizations that want the Capsule hooks trusted by policy and non-removable, Codex also supports [managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration) — a `requirements.toml` delivered at `/etc/codex/requirements.toml` or as a configuration profile in the `com.openai.codex` preference domain, which JumpCloud can distribute as a Custom macOS MDM Configuration Profile alongside this command.

### Step 1: Download the Configuration

1. Log in to the **Capsule Security** portal
2. Navigate to **Settings > Integrations**
3. Locate the **Codex** integration
4. Click **Install** and select **Mac** as the target platform
5. Download the `hooks.json` file


### Step 2: Create the Command

1. Log in to the **JumpCloud Admin Portal**
2. Navigate to **DEVICE MANAGEMENT > Commands**
3. Click **(+)** and select **Command**
4. On the **Details** tab, configure the command:
  - **Name**: Deploy Capsule Security Codex Hooks
  - **Type**: **Mac**
  - **Run As user**: **root** (required to write into each user's home directory below)
5. Paste the following into the **Command** field, replacing the placeholder line with the contents of the downloaded `hooks.json` (keep the `CAPSULE_HOOKS_EOF` marker lines unchanged and unindented):

```bash
#!/bin/bash

for USER_HOME in /Users/*/; do
    USERNAME=$(basename "$USER_HOME")
    if [ "$USERNAME" = "Shared" ] || [ "$USERNAME" = ".localized" ]; then
        continue
    fi
    CODEX_DIR="$USER_HOME/.codex"
    mkdir -p "$CODEX_DIR"
    cat > "$CODEX_DIR/hooks.json" << 'CAPSULE_HOOKS_EOF'
<PASTE YOUR HOOKS.JSON CONTENT HERE>
CAPSULE_HOOKS_EOF
    chmod 644 "$CODEX_DIR/hooks.json"
    chown "$USERNAME" "$CODEX_DIR" "$CODEX_DIR/hooks.json"
done
exit 0
```


### Step 3: Bind and Run

1. Select the **Device Groups** tab (or the **Devices** tab) and bind the target device groups or devices
2. Click **Save**
3. On the **Commands** page, click **Run Now** to execute the command, or configure a schedule so it re-runs to cover users created later
4. Review the **Results** tab to confirm the command completed successfully


### Verification

After the command reports success, close any running Codex CLI sessions on target devices, then have each user:

1. Start a new Codex CLI session so the hooks configuration is loaded
2. If Codex warns that hooks require review, run `/hooks`, review the Capsule hooks, and trust them — Codex [skips non-managed hooks](https://developers.openai.com/codex/hooks) until the user trusts them, and trust must be re-granted whenever the deployed configuration changes
3. In the Capsule portal, navigate to **Inventory > Agents** and confirm the Codex agent appears with session, prompt, response, and tool-invocation events


## Key Considerations

- Commands run as `root`, so they can create the target directories and write the configuration files — including into each user's home for the per-user integrations — without additional privileges
- To update configurations, edit the command's script and re-run it on the bound devices
- Use JumpCloud Device Groups for dynamic targeting and staged rollouts
- All four integrations can be deployed as separate commands and bound independently
- **GitHub Copilot** and **Codex** use per-user paths (`~/Library/Application Support/Code/User/hooks/hooks.json` and `~/.codex/hooks.json`), so a single run only covers user accounts that exist at execution time — schedule the command to re-run so it covers users created later
- Restart each application on target devices after deployment for hooks to take effect


## Support

For help with deployment:

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


## References

- [JumpCloud Commands — Get Started](https://jumpcloud.com/support/get-started-commands)
- [JumpCloud — Create a Command](https://jumpcloud.com/support/create-a-command-manually)
- [Codex Hooks](https://developers.openai.com/codex/hooks)
- [Codex Managed Configuration](https://developers.openai.com/codex/enterprise/managed-configuration)