JumpCloud Distribution (macOS)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

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):

   #!/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):

   #!/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):

   #!/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 — 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):

   #!/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 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
• JumpCloud — Create a Command
• Codex Hooks
• Codex Managed Configuration