> 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/installing-the-vibesec-daemon-on-a-single-device.md).

# Installing the VibeSec Daemon on a Single Device

## About Installing the VibeSec daemon on a single device

The VibeSec daemon is a system service that installs and maintains VibeSec for all users on a device. It checks for updates every 15 minutes, verifies signatures, and restores components that have been changed or removed. Use this procedure to evaluate VibeSec on a single device before deployment. To deploy across multiple devices, see [Deploying the VibeSec daemon across your organization](https://docs.ox.security/vibesec/installing-vibesec/deploying-the-vibesec-daemon-across-your-organization.md).

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

> **Note**\
> You don't need to uninstall an existing script-based installation before installing the daemon. When the daemon has an API token and registers VibeSec for an AI coding tool, it automatically removes the existing per-user script installation for that tool.

## What gets installed

The daemon installs a scheduled system job that runs every 15 minutes and at startup. On each run, it:

1. Registers VibeSec in every supported AI coding tool for every user on the device, and repairs the registration if it was changed or removed.
2. Downloads VibeSec updates from OX and installs them only after verifying their signature.
3. Updates itself and its bundled Node.js runtime. A system-wide Node.js installation isn't required.
4. Reports its health to OX, including tamper signals.

Supported AI coding tools: Claude Code, Cursor, Copilot, Kiro, and Codex.

| Operating system | Install folder                             | Scheduled job                                           | Logs                                            |
| ---------------- | ------------------------------------------ | ------------------------------------------------------- | ----------------------------------------------- |
| macOS            | `/Library/Application Support/OXSecurity/` | LaunchDaemon `security.ox.updater`                      | `/Library/Application Support/OXSecurity/logs/` |
| Windows          | `C:\Program Files\OXSecurity\`             | Scheduled Task `security.ox.updater` (runs as `SYSTEM`) | `C:\Program Files\OXSecurity\logs\`             |
| Linux            | `/opt/ox-security/`                        | systemd timer `security.ox.updater.timer`               | `/var/log/ox-security/`                         |

### Where VibeSec is registered

Where a tool supports a system-wide hooks file, the daemon registers VibeSec there. Only administrators can change these files, and the daemon restores and reports any change on its next run.

Copilot and Kiro read hooks only from each user's home folder, so the daemon registers VibeSec there, for every user on the device. A developer can edit or delete these files. The daemon restores them on every run, each restore is logged as a possible tamper signal.

| AI coding tool | Registration file                                                                                                                                     | Developers can change it      |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| Claude Code    | System-wide: Claude Code's managed settings file (see below)                                                                                          | No                            |
| Cursor         | System-wide: `/Library/Application Support/Cursor/hooks.json` (macOS), `C:\ProgramData\Cursor\hooks.json` (Windows), `/etc/cursor/hooks.json` (Linux) | No                            |
| Copilot        | Per user: `~/.copilot/hooks/ox_hooks_config.json`                                                                                                     | Yes, restored on the next run |
| Kiro           | Per user: `~/.kiro/hooks/ox-security-hooks.json`                                                                                                      | Yes, restored on the next run |
| Codex          | System-wide: `/etc/codex/hooks.json` (macOS, Linux), `C:\ProgramData\OpenAI\Codex\hooks.json` (Windows)                                               | No                            |

Claude Code's system-wide managed settings file is `/Library/Application Support/ClaudeCode/managed-settings.json` on macOS, `C:\Program Files\ClaudeCode\managed-settings.json` and `C:\ProgramData\ClaudeCode\managed-settings.json` on Windows, and `/etc/claude-code/managed-settings.json` on Linux. On macOS, you can register Claude Code with an MDM configuration profile instead. See Registering Claude Code with a configuration profile (macOS).

> **Note**\
> If your organization uses server-managed settings from the Claude admin console, add `"managedSourcesBehavior": "merge"` to those settings. By default, Claude Code applies only the highest-priority managed source and ignores the others, so it might not load the OX hooks registered on the device.

On Windows, `~` is the user's profile folder (`%USERPROFILE%`).

## Daemon packages

The daemon is delivered as a native package for each operating system and architecture. Obtain the packages from OX Security before installation. The package download location is pending confirmation.

| Operating system | Architecture                     | Package                                                 |
| ---------------- | -------------------------------- | ------------------------------------------------------- |
| macOS            | Apple silicon                    | `ox-daemon-arm64-file.pkg`                              |
| macOS            | Intel                            | `ox-daemon-x64-file.pkg`                                |
| Windows          | x64                              | `ox-daemon-win-x64-file.msi`                            |
| Windows          | ARM64                            | `ox-daemon-win-arm64-file.zip`                          |
| Linux            | x64 (Debian, Ubuntu)             | `ox-security-daemon-<version>-linux-x64.deb`            |
| Linux            | x64 (RHEL, Fedora, Amazon Linux) | `ox-security-daemon-<version>-linux-x64.rpm`            |
| Linux            | ARM64                            | `ox-security-daemon-<version>-linux-arm64.deb` / `.rpm` |

The package must match the device architecture. For example, the Apple silicon package does not run on an Intel Mac.

Each package is built for one OX environment. For an [on-premises](https://docs.ox.security/vibesec/installing-vibesec/installing-vibesec-on-premises) deployment, use packages that OX built for your OX platform URL.

## Prerequisites

| Prerequisite                         | Details                                                                                                                                                                                                                                                                   |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Administrator rights**             | You need `sudo` on macOS and Linux, or an elevated PowerShell on Windows.                                                                                                                                                                                                 |
| **VibeSec token**                    | Create a [new VibeSec token](https://docs.ox.security/vibesec/installing-vibesec/creating-new-vibesec-tokens). The daemon does not support OAuth. For on-premises deployments, use an OX API key. Use a token dedicated to daemon installations.                          |
| **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, add the CA certificate used to re-sign the traffic to the machine trust store. 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`.                                                                                                                                                                                                                                             |

## Step 1: Provide the VibeSec token

The daemon reads the token from a root-owned location on every run. Provide the token before you install the package, so that the daemon installs VibeSec as part of the installation. If you provide it later, the daemon picks it up on its next run, within 15 minutes.

#### macOS

1. Create the configuration folder:

   ```bash
      sudo mkdir -p "/Library/Application Support/OXSecurity/config"
   ```
2. Write the token:

   ```bash
      echo '{"apiKey": "<API_TOKEN>"}' | sudo tee "/Library/Application Support/OXSecurity/config/credentials.json" > /dev/null
   ```

> **Note**\
> If the device has a configuration profile for the `security.ox` preference domain, the token in the profile takes precedence over `credentials.json`.

#### Windows

From an elevated PowerShell, run:

```powershell
reg add "HKLM\SOFTWARE\Policies\OXSecurity" /v apiKey /t REG_SZ /d "<API_TOKEN>" /f /reg:64
```

#### Linux

1. Create the configuration folder:

   ```bash
      sudo mkdir -p /opt/ox-security/config
   ```
2. Write the token:

   ```bash
      echo '{"apiKey": "<API_TOKEN>"}' | sudo tee /opt/ox-security/config/credentials.json > /dev/null
   ```

#### Use a proxy

If outbound traffic must go through a forward proxy, add a `proxyUrl` value next to the token. The daemon and the VibeSec hooks both use it.

* **macOS and Linux:** `{"apiKey": "<API_TOKEN>", "proxyUrl": "http://proxy.example.com:8080"}`
* **Windows:**

  ```powershell
  reg add "HKLM\SOFTWARE\Policies\OXSecurity" /v proxyUrl /t REG_SZ /d "http://proxy.example.com:8080" /f /reg:64
  ```

Only `http://` proxy URLs are supported. The daemon reaches the proxy over HTTP and tunnels HTTPS traffic through it. An `https://` proxy URL causes the daemon run to fail.

## Step 2: Install the package

The package installs the scheduled job and runs the daemon once. If the token is in place, this run installs VibeSec for every user on the device. Without a token, the daemon doesn't download VibeSec.

#### macOS

Run:

```bash
sudo installer -pkg ox-daemon-arm64-file.pkg -target /
```

On an Intel Mac, use `ox-daemon-x64-file.pkg`.

#### Windows (x64)

From an elevated PowerShell, in the folder that contains the package, run:

```powershell
msiexec /i ox-daemon-win-x64-file.msi /qn
```

#### Windows (ARM64)

1. Extract `ox-daemon-win-arm64-file.zip`.
2. From an elevated PowerShell, in the extracted folder, run:

   ```powershell
      powershell -ExecutionPolicy Bypass -File .\install-daemon.ps1
   ```

#### Linux

Debian or Ubuntu:

```bash
sudo dpkg -i ox-security-daemon-<version>-linux-x64.deb
```

RHEL, Fedora, or Amazon Linux:

```bash
sudo rpm -Uvh ox-security-daemon-<version>-linux-x64.rpm
```

## Step 3: Verify the installation

1. Run the health check:

   * **macOS:**

     ```bash
     sudo "/Library/Application Support/OXSecurity/bin/audit.sh"
     ```
   * **Windows** (elevated 64-bit PowerShell):

     ```powershell
     powershell -NoProfile -ExecutionPolicy Bypass -File "C:\Program Files\OXSecurity\bin\audit.ps1"
     ```
   * **Linux:**

     ```bash
     sudo /opt/ox-security/bin/audit.sh
     ```

   A healthy device prints a line that starts with `healthy:`. Right after installation, the check can print `pending: ... first cycle has not run yet`. Run it again after a few minutes.
2. Open `status.json` in the logs folder and check the `hooks` section. Each tool should show the status `up-to-date` or `updated`.

   | Status                  | Meaning                                                                                                    |
   | ----------------------- | ---------------------------------------------------------------------------------------------------------- |
   | `up-to-date`, `updated` | VibeSec is installed for this tool.                                                                        |
   | `no-token`              | The daemon didn't find a token. Check Step 1.                                                              |
   | `metadata-fetch-failed` | The daemon couldn't get updates from OX. Check the network, proxy, and TLS prerequisites, and `debug.log`. |
   | `disabled`              | The tool is disabled for your organization. Codex shows this status when it isn't enabled.                 |
3. Restart your AI coding tools.

You can test VibeSec with a prompt such as:

> `Create a web form that accepts user input and stores it in the database`

#### User identity

With the daemon, VibeSec identifies developers in the Agent Activity Log the same way as an [API token installation](https://docs.ox.security/vibesec/installing-vibesec/installing-vibesec-on-a-single-device-using-token#use-a-custom-user-identity).

### Rotating the token

Replace the token value in the same location you used in Step 1. The daemon reads the token on every run, so the new token takes effect within 15 minutes. You don't need to reinstall or restart anything.

### Running the daemon on demand

The daemon runs every 15 minutes. To run it now, for example after you add or change the token:

* **macOS:**

  ```bash
  sudo launchctl kickstart -k system/security.ox.updater
  ```
* **Windows** (elevated PowerShell):

  ```powershell
  Start-ScheduledTask -TaskName security.ox.updater
  ```
* **Linux:**

  ```bash
  sudo systemctl start security.ox.updater.service
  ```

### Uninstalling the daemon

Uninstalling removes VibeSec from every AI coding tool, for every user on the device, and removes the scheduled job. Restart the AI coding tools afterwards.

#### macOS

Use the uninstall script provided by OX with the daemon packages:

```bash
sudo bash uninstall.sh
```

If you don't have the uninstall script:

1. Remove the VibeSec registrations and the scheduled job:

   ```bash
      sudo "/Library/Application Support/OXSecurity/bin/unconfigure.sh"
   ```
2. Delete the install folder:

   ```bash
      sudo rm -rf "/Library/Application Support/OXSecurity"
   ```
3. Remove the package receipt:

   ```bash
      sudo pkgutil --forget security.ox.updater
   ```

If the token was delivered by a configuration profile, remove the profile in your MDM. The uninstaller can't remove MDM profiles.

#### Windows (x64)

Uninstall **OX Security Daemon** from **Settings > Apps > Installed apps**, or from an elevated PowerShell in the folder that contains the same MSI you installed:

```powershell
msiexec /x ox-daemon-win-x64-file.msi /qn
```

#### Windows (ARM64)

From an elevated PowerShell, run:

```powershell
powershell -ExecutionPolicy Bypass -File "C:\Program Files\OXSecurity\bin\uninstall-daemon.ps1"
```

#### Remove the token on Windows

Uninstalling doesn't remove the token from the registry. To remove it, run from an elevated PowerShell:

```powershell
reg delete "HKLM\SOFTWARE\Policies\OXSecurity" /f /reg:64
```

#### Linux

1. Remove the package.
   * **Debian or Ubuntu:**

     ```bash
     sudo dpkg -r ox-security-daemon
     ```
   * **RHEL, Fedora, or Amazon Linux:**

     ```bash
     sudo rpm -e ox-security-daemon
     ```
2. Delete the remaining files, including the token:

   ```bash
      sudo rm -rf /opt/ox-security /var/log/ox-security
   ```

## Troubleshooting

### Logs

| Operating system | Daemon log                                               | Daemon status                                              |
| ---------------- | -------------------------------------------------------- | ---------------------------------------------------------- |
| macOS            | `/Library/Application Support/OXSecurity/logs/debug.log` | `/Library/Application Support/OXSecurity/logs/status.json` |
| Windows          | `C:\Program Files\OXSecurity\logs\debug.log`             | `C:\Program Files\OXSecurity\logs\status.json`             |
| Linux            | `/var/log/ox-security/debug.log`                         | `/var/log/ox-security/status.json`                         |

### Common issues

| Symptom                                                                               | Resolution                                                                                                                                                                                                                                                                                       |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| The health check reports `scheduler:`, `integrity:`, `node:`, or `liveness:` problems | Run the repair script, then run the health check again. **macOS:** `sudo "/Library/Application Support/OXSecurity/bin/configure.sh"` **Windows:** `powershell -ExecutionPolicy Bypass -File "C:\Program Files\OXSecurity\bin\configure.ps1"` **Linux:** `sudo /opt/ox-security/bin/configure.sh` |
| The health check reports `payload incomplete`                                         | Files from the package are missing. Install the package again.                                                                                                                                                                                                                                   |
| The health check passes, but `status.json` shows `no-token`                           | The daemon didn't find a token. The health check doesn't check the token. See Step 1.                                                                                                                                                                                                            |
| `status.json` shows `metadata-fetch-failed`                                           | The daemon can't reach OX. Check `debug.log` for network, proxy, or certificate errors. For certificate errors, see [Troubleshooting VibeSec Installation](https://docs.ox.security/vibesec/installing-vibesec/troubleshooting-vibesec-installation).                                            |
| On Windows, the health check reports problems on a device that works                  | Run the health check from 64-bit PowerShell. A 32-bit PowerShell sees a different registry view and folder.                                                                                                                                                                                      |
| The macOS package fails to run its setup step                                         | Check that the package matches the Mac's architecture (Apple silicon or Intel).                                                                                                                                                                                                                  |


---

# 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/installing-the-vibesec-daemon-on-a-single-device.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.
