Skip to main content
This page walks through deploying Oso to your organization’s macOS devices using Iru.
  • Oso environment ID (find it in Settings → Environments in the Oso dashboard)
  • Admin access to the Iru platform
  • macOS devices enrolled in Iru Endpoint
  • Each device must have a user assigned in Iru with an email address. Iru substitutes $EMAIL with that address when deploying configuration profiles. To assign a user, go to Devices → select the device → Edit device details → Edit user.

​
Step 1: Deploy the configuration profile

The configuration profile writes your Oso environment settings and the assigned user’s email to each device’s managed preferences, so the installer can read them without user interaction. Prepare the profile: Copy the profile below, replace YOUR_ENVIRONMENT_ID with your Oso environment ID, and save it as oso.mobileconfig. 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PayloadContent</key>
    <array>
        <dict>
            <key>PayloadType</key>
            <string>com.apple.ManagedClient.preferences</string>
            <key>PayloadIdentifier</key>
            <string>com.osohq.oso.settings.iru</string>
            <key>PayloadUUID</key>
            <string>9A8B7C6D-5E4F-3210-9A8B-7C6D5E4F3210</string>
            <key>PayloadDisplayName</key>
            <string>Oso Settings</string>
            <key>PayloadVersion</key>
            <integer>1</integer>
            <key>PayloadEnabled</key>
            <true/>
            <key>PayloadContent</key>
            <dict>
                <key>com.osohq.oso</key>
                <dict>
                    <key>Forced</key>
                    <array>
                        <dict>
                            <key>mcx_preference_settings</key>
                            <dict>
                                <key>OSO_ENVIRONMENT</key>
                                <string>YOUR_ENVIRONMENT_ID</string>
                                <key>OSO_PROXY_URL</key>
                                <string>https://agents.osohq.cloud</string>
                                <key>OSO_API_URL</key>
                                <string>https://cloud.osohq.com</string>
                                <key>USER_EMAIL</key>
                                <string>$EMAIL</string>
                            </dict>
                        </dict>
                    </array>
                </dict>
            </dict>
        </dict>
    </array>
    <key>PayloadDescription</key>
    <string>Configures Oso for AI traffic monitoring.</string>
    <key>PayloadDisplayName</key>
    <string>Oso</string>
    <key>PayloadIdentifier</key>
    <string>com.osohq.oso.profile.iru</string>
    <key>PayloadOrganization</key>
    <string>Oso Security, Inc.</string>
    <key>PayloadRemovalDisallowed</key>
    <false/>
    <key>PayloadScope</key>
    <string>System</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadUUID</key>
    <string>8B9C0D1E-2F3A-4567-8B9C-0D1E2F3A4567</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
</dict>
</plist>
Upload to Iru:
  1. Go to Library and click Add Library Item.
  2. Search for and select Custom Profile.
  3. Set the Name to Oso.
  4. Click Upload Profile and attach the edited oso.mobileconfig.
  5. Under Blueprints, assign the profile to your target blueprint(s).
  6. Click Save.

​
Step 2: Deploy the install script

The install script runs silently on each device and does two things: it configures your coding agents (Claude Code, Cursor, Codex) to route traffic through Oso for session monitoring, and it registers the device and user with Oso for identity correlation. It reads OSO_ENVIRONMENT and USER_EMAIL directly from the managed plist written in Step 1, with no user interaction required.
  1. Go to Library and click Add Library Item.
  2. Search for and select Custom Script.
  3. Set the Name to Oso Install.
  4. Under Blueprints, assign the script to your target blueprint(s).
  5. Set Execution Frequency to Install once per device.
  6. Paste the script below into the Audit Script field.
  7. Click Save.
#!/bin/bash
set -euo pipefail

PLIST="/Library/Managed Preferences/com.osohq.oso.plist"

OSO_ENVIRONMENT=$(defaults read "$PLIST" OSO_ENVIRONMENT 2>/dev/null || true)
if [[ -z "$OSO_ENVIRONMENT" ]]; then
    echo "ERROR: OSO_ENVIRONMENT not set. Deploy oso.mobileconfig first." >&2
    exit 1
fi

USER_EMAIL=$(defaults read "$PLIST" USER_EMAIL 2>/dev/null || true)
if [[ -z "$USER_EMAIL" ]]; then
    echo "ERROR: USER_EMAIL not set. Assign a user with an email address to this device in Iru." >&2
    exit 1
fi

echo "Installing Oso for $USER_EMAIL (env: $OSO_ENVIRONMENT)..."

curl -fsSL https://install.osohq.com/install.sh | sh -s -- \
    --env "$OSO_ENVIRONMENT" \
    --email "$USER_EMAIL" \
    --force

echo "Oso installation complete."
Iru runs the audit script at each check-in until it exits 0. Once the installation succeeds, the script exits 0 and Iru marks the item as passed, so it will not run again.

​
Step 3: (Optional) Deploy the Chrome extension profile

To force-install the Oso Chrome extension, copy the profile below, replace YOUR_ENVIRONMENT_ID with your Oso environment ID, and save it as chrome.mobileconfig. Then upload and deploy it following the same steps as Step 1. 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PayloadContent</key>
    <array>
        <dict>
            <key>PayloadType</key>
            <string>com.apple.ManagedClient.preferences</string>
            <key>PayloadIdentifier</key>
            <string>com.osohq.oso.chrome.iru</string>
            <key>PayloadUUID</key>
            <string>A1B2C3D4-E5F6-7890-A1B2-C3D4E5F67890</string>
            <key>PayloadDisplayName</key>
            <string>Oso Chrome Policy</string>
            <key>PayloadVersion</key>
            <integer>1</integer>
            <key>PayloadEnabled</key>
            <true/>
            <key>PayloadContent</key>
            <dict>
                <key>com.google.Chrome</key>
                <dict>
                    <key>Forced</key>
                    <array>
                        <dict>
                            <key>mcx_preference_settings</key>
                            <dict>
                                <key>ExtensionInstallForcelist</key>
                                <array>
                                    <string>nochaaflecnmeafkagnbiabpgahpledi;https://install.osohq.com/extension/chrome/update_manifest.xml</string>
                                </array>
                            </dict>
                        </dict>
                    </array>
                </dict>
            </dict>
        </dict>
        <dict>
            <key>PayloadType</key>
            <string>com.apple.ManagedClient.preferences</string>
            <key>PayloadIdentifier</key>
            <string>com.osohq.oso.chrome.extension.iru</string>
            <key>PayloadUUID</key>
            <string>B2C3D4E5-F6A7-8901-B2C3-D4E5F6A78901</string>
            <key>PayloadDisplayName</key>
            <string>Oso Chrome Extension Managed Storage</string>
            <key>PayloadVersion</key>
            <integer>1</integer>
            <key>PayloadEnabled</key>
            <true/>
            <key>PayloadContent</key>
            <dict>
                <key>com.google.Chrome.extensions.nochaaflecnmeafkagnbiabpgahpledi</key>
                <dict>
                    <key>Forced</key>
                    <array>
                        <dict>
                            <key>mcx_preference_settings</key>
                            <dict>
                                <key>environmentId</key>
                                <string>YOUR_ENVIRONMENT_ID</string>
                                <key>userEmail</key>
                                <string>$EMAIL</string>
                            </dict>
                        </dict>
                    </array>
                </dict>
            </dict>
        </dict>
    </array>
    <key>PayloadDescription</key>
    <string>Force-installs the Oso Chrome extension and configures it for AI traffic monitoring.</string>
    <key>PayloadDisplayName</key>
    <string>Oso Chrome Extension</string>
    <key>PayloadIdentifier</key>
    <string>com.osohq.oso.chrome.profile.iru</string>
    <key>PayloadOrganization</key>
    <string>Oso Security, Inc.</string>
    <key>PayloadRemovalDisallowed</key>
    <false/>
    <key>PayloadScope</key>
    <string>System</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadUUID</key>
    <string>C3D4E5F6-A7B8-9012-C3D4-E5F6A7B89012</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
</dict>
</plist>
After the profile lands on a device, open chrome://policy/ in Chrome and click Reload policies to apply immediately.
Chrome enterprise management requirementChrome (v119+) blocks force-installation of extensions not hosted on the Chrome Web Store unless it detects the device as enterprise managed. Devices enrolled in Iru via user-approved MDM (self-enrollment) do not satisfy this requirement. Chrome requires either DEP/ADE supervision through Apple Business Manager or Chrome Browser Cloud Management (CBCM) enrollment.If chrome://policy shows [BLOCKED] next to the extension entry, enroll Chrome in CBCM:
  1. In the Google Admin Console, go to Devices → Chrome → Connectors → Browser Cloud Management enrollment tokens.
  2. Click Add enrollment token, give it a name, and copy the generated token.
  3. Add the following key to the mcx_preference_settings dict in chrome.mobileconfig, alongside ExtensionInstallForcelist:
<key>CloudManagementEnrollmentToken</key>
<string>YOUR_CBCM_TOKEN</string>
  1. Redeploy the updated profile via Iru.
  2. Fully quit and relaunch Chrome on the device (⌘Q, then reopen).
After enrollment, chrome://management will show browser management and chrome://policy will show the extension installing without [BLOCKED].

​
Verifying deployment

After devices enroll, confirm the installation succeeded: 
# Managed preferences written by the configuration profile
defaults read "/Library/Managed Preferences/com.osohq.oso"

# Tool configs written by the installer (system-level)
cat "/Library/Application Support/ClaudeCode/managed-settings.json"
cat "/Library/Application Support/Cursor/hooks.json"
cat "/etc/codex/managed_config.toml"

# Identity registered with Oso
cat "/Library/Application Support/Oso/identity.json"

# Binaries installed
ls -la /usr/local/bin/oso-hook /usr/local/bin/oso-setup