Overview

Running the installer as root writes to system-level paths that apply to all users on the machine and take precedence over any user-level configuration:

Component	Deployment method
Claude Code	File: `/Library/Application Support/ClaudeCode/managed-settings.json`
Cursor	File: `/Library/Application Support/Cursor/hooks.json`
Codex	File: `/etc/codex/managed_config.toml`
Chrome	File: `/Library/Application Support/Google/Chrome/policies/managed/oso.json`
Claude Desktop Plugin	Manual upload (see below)

Claude Desktop Plugin

The Claude Desktop Plugin cannot be deployed via a managed file path. Instead, it must be built and uploaded as an enterprise plugin through the Claude Desktop UI.

The oso-hook binary must be present at /usr/local/bin/oso-hook on each user’s machine for the plugin hooks to fire. The install script must run on every device before or alongside plugin enrollment.

How it works: When the installer runs and Claude Desktop Plugin is selected, it packages a .plugin file at /tmp/oso.plugin. The plugin contains:

.claude-plugin/plugin.json (plugin metadata)
hooks/hooks.json (hook configuration that invokes oso-hook on every session event)

To deploy to your organization:

Run the installer on any machine to produce the plugin package:

curl -fsSL https://install.osohq.com/install.sh | sudo sh -s -- \
    --env YOUR_ENVIRONMENT_ID \
    --email admin@example.com \
    --force
# Plugin packaged at /tmp/oso.plugin

Open Claude Desktop → Customize → Plugins.
Upload /tmp/oso.plugin as an enterprise plugin.
Mark the default access as Required to force install for all users.

Claude Code

The installer writes Oso hooks to /Library/Application Support/ClaudeCode/managed-settings.json, which Claude Code reads as managed policy on every device. This is the standard deployment path and works for most organizations.

curl -fsSL https://install.osohq.com/install.sh | sudo sh -s -- \
    --env YOUR_ENVIRONMENT_ID \
    --email user@example.com \
    --force

If your organization uses claude.ai server-managed settings

If your organization manages Claude Code settings centrally through claude.ai → Settings → Claude Code, you should add the Oso hooks there instead of relying on the local managed-settings.json. The install script must still run on every device to install the oso-hook binary and register the device with Oso. After running the installer, add the following to your organization’s claude.ai managed settings:

{
  "hooks": {
    "UserPromptSubmit":   [{"matcher": "", "hooks": [{"type": "command", "command": "/usr/local/bin/oso-hook", "timeout": 5}]}],
    "PreToolUse":         [{"matcher": "", "hooks": [{"type": "command", "command": "/usr/local/bin/oso-hook", "timeout": 5}]}],
    "PostToolUse":        [{"matcher": "", "hooks": [{"type": "command", "command": "/usr/local/bin/oso-hook", "timeout": 5}]}],
    "PostToolUseFailure": [{"matcher": "", "hooks": [{"type": "command", "command": "/usr/local/bin/oso-hook", "timeout": 5}]}],
    "Stop":               [{"matcher": "", "hooks": [{"type": "command", "command": "/usr/local/bin/oso-hook", "timeout": 5}]}],
    "SubagentStop":       [{"matcher": "", "hooks": [{"type": "command", "command": "/usr/local/bin/oso-hook", "timeout": 5}]}]
  }
}

For help deploying Oso across your organization via MDM, contact us.

Uninstalling

sudo /usr/local/bin/oso-setup uninstall

Reverses a managed install. For shared config files (Claude Code, Cursor, Codex), only Oso’s entries are removed, while other settings are left intact. Files Oso owns outright (Chrome and Firefox native-messaging manifests, the GitHub Copilot hook, etc.) are removed entirely. Also removes the identity file, debug logs, and the oso-hook and oso-setup binaries from /usr/local/bin. It’s safe to run more than once. For the Claude Desktop Plugin, you must separately remove the enterprise plugin through Claude Desktop → Customize → Plugins. Pass --keep-logs to retain debug logs for troubleshooting before uninstalling:

sudo /usr/local/bin/oso-setup uninstall --keep-logs

Get Started

Capabilities

Deployment Models

Integrations & Connections

Self-Hosting

Reference

Claude Desktop Plugin

Claude Code

If your organization uses claude.ai server-managed settings

Uninstalling

​Claude Desktop Plugin

​Claude Code

​If your organization uses claude.ai server-managed settings

​Uninstalling

Claude Desktop Plugin

Claude Code

If your organization uses claude.ai server-managed settings

Uninstalling