> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/vibesec/installing-vibesec/deploying-the-vibesec-daemon-across-your-organization.md).

# Deploying the VibeSec Daemon Across Your Organization

## About deploying the VibeSec daemon across your organization

Deploy the VibeSec daemon across developer devices using an MDM or endpoint management tool, such as Jamf Pro, Kandji, Microsoft Intune, Microsoft Configuration Manager, or JumpCloud. The daemon installs and maintains VibeSec for all users on each device, checks for updates every 15 minutes, and restores components that have been changed or removed. For manual installation, see [Installing the VibeSec daemon on a single device](https://docs.ox.security/vibesec/installing-vibesec/installing-the-vibesec-daemon-on-a-single-device.md).

If installation completes but no activity appears in the VibeSec dashboard, see [Troubleshooting](#troubleshooting).

## How the deployment works

A daemon deployment has three parts:

| Part                        | What it does                                                                                   | How you deploy it                                                         | Required    |
| --------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------- |
| **VibeSec token**           | Authenticates the daemon and VibeSec on the device. One token serves every user on the device. | macOS: configuration profile Windows: registry policy Linux: managed file | Yes         |
| **Daemon package**          | Installs the daemon and its scheduled job.                                                     | Your MDM's package or app deployment, running as `root` or `SYSTEM`       | Yes         |
| **Health check and repair** | Detects a daemon that stopped running or was changed, and repairs it.                          | Your MDM's detection and remediation feature, or a scheduled script       | Recommended |

The daemon repairs VibeSec on its own, but it can't restart itself if its scheduled job is removed or disabled. The health check covers that case.

## Files provided by OX

| File                                          | Used for                                                            |
| --------------------------------------------- | ------------------------------------------------------------------- |
| Daemon packages                               | Installing the daemon. See Daemon packages.                         |
| `security.ox-credentials.mobileconfig`        | macOS configuration profile template for the token and proxy.       |
| `OXSecurity.admx` and `en-US/OXSecurity.adml` | Windows administrative template for the token and proxy policies.   |
| `claudecode-ox-hooks.mobileconfig`            | Optional. See Registering Claude Code with a configuration profile. |
| `uninstall.sh`                                | Uninstalling the daemon on macOS.                                   |

## Prerequisites

| Prerequisite                         | Details                                                                                                                                                                                                                                                                                          |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **VibeSec token**                    | Create a [new VibeSec token](https://docs.ox.security/vibesec/installing-vibesec/creating-new-vibesec-tokens) for the daemon fleet. The daemon supports API token authentication only, not OAuth. For on-premises deployments, use an OX API key. Use a token dedicated to daemon installations. |
| **Daemon packages**                  | The packages for every OS and architecture in your fleet. For on-premises deployments, use packages that OX built for your OX platform URL.                                                                                                                                                      |
| **Network access**                   | If your organization restricts outbound network traffic, add the following domains to your allowlist: `api.cloud.ox.security` (or your on-premises OX platform URL) `nodejs.org` (Node.js runtime updates)                                                                                       |
| **TLS inspection and HTTPS proxies** | If your organization inspects outbound HTTPS traffic, deploy the CA certificate used to re-sign the traffic to the machine trust store of every device. The daemon uses the machine trust store. If the CA certificate isn't trusted, the daemon can't reach OX and VibeSec isn't installed.     |
| **Linux only**                       | systemd, and `dpkg` or `rpm`.                                                                                                                                                                                                                                                                    |
| Claude server-managed settings       | If your organization uses server-managed settings from the Claude admin console, add `"managedSourcesBehavior": "merge"` to those settings. Otherwise, Claude Code might not load the OX hooks registered on the device.                                                                         |

## Step 1: Deliver the VibeSec token

Deliver the token before, or together with, the package. When the token is already on the device, the daemon installs VibeSec as part of the package installation. If the token arrives later, the daemon picks it up on its next run, within 15 minutes.

The daemon reads the token on every run. To rotate the token, update it in your MDM. The new token takes effect within 15 minutes, without reinstalling anything.

Deliver the token with a mechanism your MDM keeps enforcing, such as a configuration profile or a policy. A one-time script sets the token once and doesn't restore it if it is changed, removed, corrupted, or tampered with.

#### macOS: configuration profile

Deploy a device-level (System scope) configuration profile for the `security.ox` preference domain, with these keys:

| Key        | Required | Value                                                                                                                                  |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey`   | Yes      | Your VibeSec token.                                                                                                                    |
| `proxyUrl` | No       | A forward proxy URL, `http://` only. Delete the key entirely if you don't use a proxy. An empty value isn't the same as a missing key. |

You can upload the provided `security.ox-credentials.mobileconfig` after you edit it, or enter the keys in your MDM's custom settings payload. The provided profile:

```xml
<?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>security.ox</string>
      <key>PayloadIdentifier</key>
      <string>security.ox.credentials.payload</string>
      <key>PayloadUUID</key>
      <string>6867B611-9B5E-47BC-94DD-EA495CF244A0</string>
      <key>PayloadVersion</key>
      <integer>1</integer>
      <key>PayloadDisplayName</key>
      <string>OX Security — Org API Key + Proxy</string>
      <key>apiKey</key>
      <string>REPLACE_WITH_ORG_TOKEN</string>
      <key>proxyUrl</key>
      <string>REPLACE_WITH_PROXY_URL_OR_DELETE_THIS_KEY</string>
    </dict>
  </array>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadIdentifier</key>
  <string>security.ox.credentials</string>
  <key>PayloadUUID</key>
  <string>01073670-DBAC-499F-B064-4CA262552CD3</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
  <key>PayloadDisplayName</key>
  <string>OX Security — Org Credentials</string>
  <key>PayloadScope</key>
  <string>System</string>
</dict>
</plist>
```

On the device, the profile appears as `/Library/Managed Preferences/security.ox.plist`.

#### Windows: registry policy

The daemon reads these `REG_SZ` values from `HKLM\SOFTWARE\Policies\OXSecurity`:

| Value      | Required | Data                                                                                  |
| ---------- | -------- | ------------------------------------------------------------------------------------- |
| `apiKey`   | Yes      | Your VibeSec token.                                                                   |
| `proxyUrl` | No       | A forward proxy URL, `http://` only. Don't create the value if you don't use a proxy. |

Choose one of these delivery methods:

* **Administrative template (recommended).** Import `OXSecurity.admx` and `en-US/OXSecurity.adml` into your MDM or Group Policy. The template adds two policies under **OX Security**: **OX org API key** and **OX forward proxy URL**. Leave the proxy policy **Not Configured** if you don't use a proxy.
* **Your MDM's registry setting.** For tools that can't import an administrative template, write the values with the tool's registry policy.
* **A remediation script.** Write the values with a scheduled script that runs as `SYSTEM` in 64-bit PowerShell. A 32-bit PowerShell writes to `WOW6432Node`, where the daemon doesn't look.

#### Linux: managed file

The daemon reads the token from `/opt/ox-security/config/credentials.json`. The file must be owned by `root` and readable by all users (mode `0644`), because VibeSec runs as the developer:

```json
{
  "apiKey": "<API_TOKEN>",
  "proxyUrl": "http://proxy.example.com:8080"
}
```

Omit `proxyUrl` if you don't use a proxy.

Linux has no configuration profile or registry policy, so keep the file enforced with a configuration management tool, such as an Ansible, Puppet, or Chef file resource, or run this script as `root` on a schedule. The script changes the file only when its content differs:

```bash
#!/bin/bash
set -uo pipefail

API_KEY="REPLACE_WITH_ORG_TOKEN"
PROXY_URL=""

CONFIG_DIR="/opt/ox-security/config"
FILE="${CONFIG_DIR}/credentials.json"

if [ -z "$API_KEY" ] || [ "$API_KEY" = "REPLACE_WITH_ORG_TOKEN" ]; then
  echo "API_KEY is not set" >&2
  exit 1
fi

mkdir -p "$CONFIG_DIR"

if [ -n "$PROXY_URL" ]; then
  desired="$(printf '{\n  "apiKey": "%s",\n  "proxyUrl": "%s"\n}\n' "$API_KEY" "$PROXY_URL")"
else
  desired="$(printf '{\n  "apiKey": "%s"\n}\n' "$API_KEY")"
fi

if [ -f "$FILE" ] && [ "$(cat "$FILE")" = "$desired" ]; then
  echo "VibeSec token already current"
  exit 0
fi

tmp="$(mktemp "${CONFIG_DIR}/.credentials.XXXXXX")" || exit 1
printf '%s' "$desired" > "$tmp"
chown root:root "$tmp" 2>/dev/null || true
chmod 0644 "$tmp"
mv -f "$tmp" "$FILE"
echo "VibeSec token provisioned at ${FILE}"
```

You can run the script before the package is installed. The package never overwrites an existing `credentials.json`.

> The token is stored in the script body. Restrict access to the script in your management console.

## Step 2: Deploy the daemon package

Deploy the package with your MDM's package or app deployment, or with a script that your MDM runs as `root` or `SYSTEM`.

#### Silent installation commands

| Package              | Installation command (as `root` or `SYSTEM`)                                                                                    |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| macOS `.pkg`         | `installer -pkg ox-daemon-<arch>-file.pkg -target /`                                                                            |
| Windows x64 `.msi`   | `msiexec /i ox-daemon-win-x64-file.msi /qn /norestart /l*v C:\Windows\Temp\ox-daemon-msi.log`                                   |
| Windows ARM64 `.zip` | Extract the zip, then run `powershell.exe -NoProfile -ExecutionPolicy Bypass -File install-daemon.ps1` in the extracted folder. |
| Linux `.deb`         | `dpkg -i ox-security-daemon-<version>-linux-<arch>.deb`                                                                         |
| Linux `.rpm`         | `rpm -Uvh ox-security-daemon-<version>-linux-<arch>.rpm`                                                                        |

For `msiexec`, exit code `3010` means success with a pending restart. The daemon doesn't need a restart.

#### Deployment rules

* **Match the architecture.** Target Apple silicon and Intel Macs, and x64 and ARM64 Windows devices, with their own package. Mixed-architecture fleets need one deployment per architecture, or the install script below, which picks the package for the device.
* **Detect the installation by file presence, not by version.** The daemon updates itself between package releases, so the package version doesn't describe what is running. A version-based detection rule causes needless reinstalls. Use the presence of the daemon files, for example `C:\Program Files\OXSecurity\bin\ox_daemon.js` on Windows.
* **Re-deploying is safe.** Installing the package again keeps a newer daemon and Node.js runtime that pass signature verification. It doesn't downgrade them.
* **Windows: run scripts in 64-bit PowerShell.** A 32-bit host sees `WOW6432Node` and `C:\Program Files (x86)` instead of the real install location.

#### Install script for script-based MDMs

If your MDM deploys software by running scripts, use the script for the OS. Each script does nothing when the daemon is already installed, so it is safe to run on a schedule. A scheduled run also reinstalls the package if its files were deleted.

Set either the URL of a web location that hosts the packages (for example, an internal server), or the path of a package your MDM copies to the device.

{% tabs %}
{% tab title="macOS" %}
Run as `root`.

```bash
#!/bin/bash
set -uo pipefail

# Set PKG_URL_BASE to a location that hosts the packages, or leave it empty and
# copy the package for this device's architecture to PKG.
PKG_URL_BASE=""
PKG="/var/tmp/ox-daemon.pkg"
VARIANT="file"

ROOT="/Library/Application Support/OXSecurity"

is_installed() {
  local cfg="${ROOT}/config/daemon.json" v
  for f in "${ROOT}/baseline/ox_daemon.js" "${ROOT}/baseline/ox_daemon.js.sig.json" \
           "${ROOT}/bin/configure.sh" "${ROOT}/bin/audit.sh" "$cfg"; do
    [ -f "$f" ] || return 1
  done
  v="$(sed -n 's/.*"nodeVersion"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$cfg" | head -1)"
  [ -n "$v" ] && [ -x "${ROOT}/node/${v}/bin/node" ]
}

if is_installed; then
  echo "VibeSec daemon already installed"
  exit 0
fi

if [ -n "$PKG_URL_BASE" ]; then
  case "$(uname -m)" in
    arm64) ARCH="arm64" ;;
    x86_64) ARCH="x64" ;;
    *) echo "unsupported architecture: $(uname -m)" >&2; exit 1 ;;
  esac
  echo "Downloading ox-daemon-${ARCH}-${VARIANT}.pkg"
  curl -fsSL "${PKG_URL_BASE%/}/ox-daemon-${ARCH}-${VARIANT}.pkg" -o "$PKG" \
    || { echo "download failed" >&2; exit 1; }
fi

[ -f "$PKG" ] || { echo "no package at ${PKG}" >&2; exit 1; }

installer -pkg "$PKG" -target / || { echo "installer failed" >&2; exit 1; }
rm -f "$PKG"

"${ROOT}/bin/audit.sh" || echo "Installed. The health check reports a problem; see the health check step."
```

{% endtab %}

{% tab title="Windows" %}
Run as `SYSTEM` in 64-bit PowerShell.

```powershell
# Set $PackageUrlBase to a location that hosts the packages, or leave it empty and
# copy the package for this device's architecture to $LocalFile.
$PackageUrlBase = ''
$LocalFile = 'C:\Windows\Temp\ox-daemon-win-x64-file.msi'

$InstallRoot = 'C:\Program Files\OXSecurity'

function Test-DaemonInstalled {
  $cfg = Join-Path $InstallRoot 'config\daemon.json'
  foreach ($f in @(
    (Join-Path $InstallRoot 'baseline\ox_daemon.js'),
    (Join-Path $InstallRoot 'baseline\ox_daemon.js.sig.json'),
    (Join-Path $InstallRoot 'bin\configure.ps1'),
    (Join-Path $InstallRoot 'bin\audit.ps1'),
    $cfg
  )) {
    if (-not (Test-Path -LiteralPath $f)) { return $false }
  }
  try { $v = (Get-Content $cfg -Raw | ConvertFrom-Json).nodeVersion } catch { return $false }
  if (-not $v) { return $false }
  return (Test-Path -LiteralPath (Join-Path $InstallRoot "node\$v\node.exe"))
}

if (Test-DaemonInstalled) {
  Write-Output 'VibeSec daemon already installed'
  exit 0
}

switch ($env:PROCESSOR_ARCHITECTURE) {
  'AMD64' { $arch = 'x64' }
  'ARM64' { $arch = 'arm64' }
  default { Write-Error "unsupported architecture: $env:PROCESSOR_ARCHITECTURE"; exit 1 }
}
$ext = if ($arch -eq 'x64') { 'msi' } else { 'zip' }

if ($PackageUrlBase) {
  $name = "ox-daemon-win-$arch-file.$ext"
  $LocalFile = Join-Path $env:TEMP $name
  Write-Output "Downloading $name"
  [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
  try {
    Invoke-WebRequest -Uri "$($PackageUrlBase.TrimEnd('/'))/$name" -OutFile $LocalFile -UseBasicParsing
  } catch {
    Write-Error "download failed: $_"; exit 1
  }
}

if (-not (Test-Path -LiteralPath $LocalFile)) {
  Write-Error "no package at $LocalFile"; exit 1
}

if ($ext -eq 'msi') {
  $p = Start-Process msiexec.exe -Wait -PassThru -ArgumentList @(
    '/i', "`"$LocalFile`"", '/qn', '/norestart',
    '/l*v', 'C:\Windows\Temp\ox-daemon-msi.log'
  )
  if ($p.ExitCode -ne 0 -and $p.ExitCode -ne 3010) {
    Write-Error "msiexec failed with $($p.ExitCode) - see C:\Windows\Temp\ox-daemon-msi.log"
    exit 1
  }
} else {
  $stage = Join-Path $env:TEMP "ox-daemon-$PID"
  Remove-Item $stage -Recurse -Force -ErrorAction SilentlyContinue
  Expand-Archive -LiteralPath $LocalFile -DestinationPath $stage -Force
  & powershell.exe -NoProfile -ExecutionPolicy Bypass -File (Join-Path $stage 'install-daemon.ps1')
  if ($LASTEXITCODE -ne 0) { Write-Error "install-daemon.ps1 failed with $LASTEXITCODE"; exit 1 }
  Remove-Item $stage -Recurse -Force -ErrorAction SilentlyContinue
}
Remove-Item $LocalFile -Force -ErrorAction SilentlyContinue

& powershell.exe -NoProfile -ExecutionPolicy Bypass -File (Join-Path $InstallRoot 'bin\audit.ps1')
if ($LASTEXITCODE -ne 0) {
  Write-Output 'Installed. The health check reports a problem; see the health check step.'
}
```

{% endtab %}

{% tab title="Linux" %}
Run as `root`.

```bash
#!/bin/bash
set -uo pipefail

# Set PKG_URL_BASE and VERSION to download the package, or leave PKG_URL_BASE empty
# and copy the package for this device to PKG.
PKG_URL_BASE=""
VERSION=""
PKG=""

ROOT="/opt/ox-security"

is_installed() {
  local cfg="${ROOT}/config/daemon.json" v
  for f in "${ROOT}/baseline/ox_daemon.js" "${ROOT}/baseline/ox_daemon.js.sig.json" \
           "${ROOT}/bin/configure.sh" "${ROOT}/bin/audit.sh" "$cfg"; do
    [ -f "$f" ] || return 1
  done
  v="$(sed -n 's/.*"nodeVersion"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$cfg" | head -1)"
  [ -n "$v" ] && [ -x "${ROOT}/node/${v}/bin/node" ]
}

if is_installed; then
  echo "VibeSec daemon already installed"
  exit 0
fi

command -v systemctl >/dev/null 2>&1 || { echo "systemd is required" >&2; exit 1; }

if command -v dpkg >/dev/null 2>&1; then
  FORMAT="deb"
elif command -v rpm >/dev/null 2>&1; then
  FORMAT="rpm"
else
  echo "neither dpkg nor rpm found" >&2
  exit 1
fi

if [ -n "$PKG_URL_BASE" ]; then
  [ -n "$VERSION" ] || { echo "set VERSION when using PKG_URL_BASE" >&2; exit 1; }
  case "$(uname -m)" in
    x86_64) ARCH="x64" ;;
    aarch64 | arm64) ARCH="arm64" ;;
    *) echo "unsupported architecture: $(uname -m)" >&2; exit 1 ;;
  esac
  NAME="ox-security-daemon-${VERSION}-linux-${ARCH}.${FORMAT}"
  PKG="/var/tmp/${NAME}"
  echo "Downloading ${NAME}"
  curl -fsSL "${PKG_URL_BASE%/}/${NAME}" -o "$PKG" || { echo "download failed" >&2; exit 1; }
fi

[ -n "$PKG" ] && [ -f "$PKG" ] || { echo "no package" >&2; exit 1; }

if [ "$FORMAT" = "deb" ]; then
  dpkg -i "$PKG" || { echo "dpkg failed" >&2; exit 1; }
else
  rpm -Uvh "$PKG" || { echo "rpm failed" >&2; exit 1; }
fi
rm -f "$PKG"

"${ROOT}/bin/audit.sh" || echo "Installed. The health check reports a problem; see the health check step."
```

{% endtab %}
{% endtabs %}

## Step 3: Monitor and repair daemon health (recommended)

Every daemon package includes a health check script and a repair script. Run them from your MDM so that a daemon that stops running is detected and fixed.

| Operating system | Health check                                           | Repair                                                     |
| ---------------- | ------------------------------------------------------ | ---------------------------------------------------------- |
| macOS            | `/Library/Application Support/OXSecurity/bin/audit.sh` | `/Library/Application Support/OXSecurity/bin/configure.sh` |
| Windows          | `C:\Program Files\OXSecurity\bin\audit.ps1`            | `C:\Program Files\OXSecurity\bin\configure.ps1`            |
| Linux            | `/opt/ox-security/bin/audit.sh`                        | `/opt/ox-security/bin/configure.sh`                        |

The health check verifies that:

* The daemon passes signature verification.
* The scheduled job is loaded (macOS), registered and enabled (Windows), or enabled and active (Linux).
* The Node.js runtime passes verification and runs.
* The daemon completed a run in the last 60 minutes.

It exits `0` when the device is healthy, and `1` with one line per problem when it isn't. Every problem has the same fix: run the repair script. The repair script is safe to run at any time. It keeps a daemon that passes verification, restores one that doesn't, never downgrades the Node.js runtime, and starts a daemon run.

The health check doesn't report two conditions, because the repair script can't fix them:

* **Missing package files.** The health check prints `payload incomplete` and exits `0`. Reinstalling the package fixes this. Your package deployment or the install script handles it.
* **A missing token.** The daemon runs but doesn't download VibeSec. Your token delivery handles it.

Run the health check every hour, as `root` or `SYSTEM`. On Windows, run it in 64-bit PowerShell.

#### Combined health check and repair script

If your MDM has a detection and remediation feature, use the health check as the detection script and the repair script as the remediation. Configure the detection and remediation steps using the corresponding features in your MDM.

If your MDM only runs scripts, schedule this script to run every hour. It runs the repair only when the health check fails, so its result in your MDM is a health signal.

{% tabs %}
{% tab title="macOS" %}
Run as `root`.

```bash
#!/bin/bash
set -uo pipefail

ROOT="/Library/Application Support/OXSecurity"
AUDIT="${ROOT}/bin/audit.sh"
CONFIGURE="${ROOT}/bin/configure.sh"

if [ ! -x "$AUDIT" ] || [ ! -x "$CONFIGURE" ]; then
  echo "VibeSec daemon not installed"
  exit 0
fi

if output="$("$AUDIT" 2>&1)"; then
  echo "$output"
  exit 0
fi

echo "PROBLEM DETECTED:"
echo "$output"
echo "--- repairing ---"
"$CONFIGURE"
launchctl kickstart -k system/security.ox.updater 2>/dev/null || true

echo "--- checking again ---"
"$AUDIT"
```

{% endtab %}

{% tab title="Windows" %}
Run as `SYSTEM` in 64-bit PowerShell.

```powershell
$InstallRoot = 'C:\Program Files\OXSecurity'
$audit = Join-Path $InstallRoot 'bin\audit.ps1'
$configure = Join-Path $InstallRoot 'bin\configure.ps1'

if (-not (Test-Path -LiteralPath $audit) -or -not (Test-Path -LiteralPath $configure)) {
  Write-Output 'VibeSec daemon not installed'
  exit 0
}

$output = & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $audit 2>&1
if ($LASTEXITCODE -eq 0) {
  Write-Output $output
  exit 0
}

Write-Output 'PROBLEM DETECTED:'
Write-Output $output
Write-Output '--- repairing ---'
& powershell.exe -NoProfile -ExecutionPolicy Bypass -File $configure
Start-ScheduledTask -TaskName security.ox.updater -ErrorAction SilentlyContinue

Write-Output '--- checking again ---'
& powershell.exe -NoProfile -ExecutionPolicy Bypass -File $audit
```

{% endtab %}

{% tab title="Linux" %}
Run as `root`.

```bash
#!/bin/bash
set -uo pipefail

ROOT="/opt/ox-security"
AUDIT="${ROOT}/bin/audit.sh"
CONFIGURE="${ROOT}/bin/configure.sh"

if [ ! -x "$AUDIT" ] || [ ! -x "$CONFIGURE" ]; then
  echo "VibeSec daemon not installed"
  exit 0
fi

if output="$("$AUDIT" 2>&1)"; then
  echo "$output"
  exit 0
fi

echo "PROBLEM DETECTED:"
echo "$output"
echo "--- repairing ---"
"$CONFIGURE"
systemctl start security.ox.updater.service --no-block 2>/dev/null || true

echo "--- checking again ---"
"$AUDIT"
```

{% endtab %}
{% endtabs %}

## Step 4: Verify the deployment

1. On a target device, run the health check (see Step 3). A healthy device prints a line that starts with `healthy:`. Right after installation, it can print `pending: ... first cycle has not run yet`.
2. Open `status.json` in the daemon's logs folder and check that each tool in the `hooks` section shows `up-to-date` or `updated`. If it shows `no-token`, the token didn't reach the device. See Verify the installation for the other statuses.
3. Restart an AI coding tool on the device and send a test prompt. Confirm that the activity appears in the VibeSec dashboard.
4. In your MDM, confirm that the health check reports the device as healthy.

### Registering Claude Code with a configuration profile (macOS)

By default, the daemon registers VibeSec in Claude Code's system-wide managed settings file. On macOS, you can deliver Claude Code's registration as a configuration profile instead, for example if you already manage Claude Code with a profile for the `com.anthropic.claudecode` preference domain.

> **Important**\
> When a Mac has a `com.anthropic.claudecode` configuration profile, the daemon leaves Claude Code's registration to that profile. If you manage Claude Code with a profile, the profile must include the OX hooks. Otherwise, Claude Code isn't protected on those Macs.

1. Deploy the provided `claudecode-ox-hooks.mobileconfig` as a device-level (System scope) profile, the same way you deploy the token profile. If you already deploy a Claude Code profile, add the `hooks` key from `claudecode-ox-hooks.mobileconfig` to your existing profile instead, so that each Mac has one Claude Code profile.
2. Choose the package:
   * `ox-daemon-<arch>-file.pkg`: the daemon registers VibeSec in Claude Code's managed settings file only while a Mac has no Claude Code profile, for example before the profile arrives. so Claude Code is protected in the meantime.
   * `ox-daemon-<arch>-profile.pkg`: the daemon never registers VibeSec in Claude Code's managed settings file. With the install script, set `VARIANT="profile"`.

> **Note**\
> If your organization uses server-managed settings from the Claude admin console, add `"managedSourcesBehavior": "merge"` to those settings. Otherwise, Claude Code might ignore the OX hooks delivered through the configuration profile.

The other AI coding tools aren't affected.

### Migrating existing installations

You do not need to uninstall existing per-user VibeSec installations before deploying the daemon.

1. Deploy the token and the daemon package to the devices (Steps 1 to 3).
2. Remove or unassign the scheduled VibeSec installation script command in your MDM. Otherwise, the script reinstalls the per-user installation that the daemon removes.
3. Ask developers to restart their AI coding tools.

When the daemon has an API token and registers VibeSec for a tool, it automatically removes the existing per-user script installation of that tool from every user's home folder.

After the migration, activity from devices that used OAuth is authenticated with the daemon's API token. Developers are identified by their Git user email, as with [API token installations](https://docs.ox.security/vibesec/installing-vibesec/installing-vibesec-on-a-single-device-using-token#use-a-custom-user-identity).

### Updating the daemon

The daemon updates itself, VibeSec, and its Node.js runtime. You don't need to deploy a new package for updates.

### Uninstalling at scale

1. Unassign the package deployment and the health check from the devices. Otherwise, your MDM reinstalls or repairs the daemon.
2. Run the uninstaller on the devices:

   | Operating system | Uninstall                                                                                                                       |
   | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
   | macOS            | Run the provided `uninstall.sh` as `root`.                                                                                      |
   | Windows x64      | Uninstall the MSI with your MDM, or run `msiexec /x ox-daemon-win-x64-file.msi /qn /norestart` using the MSI you last deployed. |
   | Windows ARM64    | Run `C:\Program Files\OXSecurity\bin\uninstall-daemon.ps1` as `SYSTEM`.                                                         |
   | Linux            | Remove the `ox-security-daemon` package, then delete `/opt/ox-security` and `/var/log/ox-security`.                             |

   Uninstalling removes VibeSec from every AI coding tool, for every user on the device.
3. Remove the token from your endpoint management configuration: unassign the macOS token profile (and the Claude Code hooks profile, if deployed), remove the Windows registry policy, and remove the managed Linux `/opt/ox-security/config/credentials.json` file. If you deliver the token with a script, stop that script too, including Windows remediation scripts and Linux provisioning scripts. The uninstaller can't remove MDM-managed settings.

## Troubleshooting

| Symptom                                                                             | Resolution                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The health check passes, but no activity appears and `status.json` shows `no-token` | The token didn't reach the device. On macOS, check that `/Library/Managed Preferences/security.ox.plist` exists. On Windows, check `HKLM\SOFTWARE\Policies\OXSecurity` in the 64-bit registry. On Linux, check `/opt/ox-security/config/credentials.json`.                                                                  |
| `status.json` shows `metadata-fetch-failed`                                         | The daemon can't reach OX. Check the network, proxy, and TLS prerequisites, and the daemon's `debug.log`.                                                                                                                                                                                                                   |
| Claude Code isn't protected, but the other AI coding tools are                      | If your organization uses Claude server-managed settings, verify that `"managedSourcesBehavior": "merge"` is configured on every operating system. On macOS, if a `com.anthropic.claudecode` configuration profile is used, verify that it contains the OX hooks. See Registering Claude Code with a configuration profile. |
| The health check reports problems on Windows devices that work                      | The script runs in 32-bit PowerShell. Run it in 64-bit PowerShell.                                                                                                                                                                                                                                                          |
| The health check keeps failing after repair                                         | Check the daemon's `debug.log`. If the health check reports `payload incomplete`, reinstall the package.                                                                                                                                                                                                                    |
| The macOS package fails to install                                                  | Check that the package matches the Mac's architecture. Review the installation logs for additional errors.                                                                                                                                                                                                                  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ox.security/vibesec/installing-vibesec/deploying-the-vibesec-daemon-across-your-organization.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
