> 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-vibesec-on-premises.md).

# Installing VibeSec On-Premises

Use this procedure to install VibeSec when your organization uses a self-hosted (on-premises) OX Security deployment.

Unlike SaaS deployments, on-premises deployments don't support OAuth authentication. Instead, VibeSec authenticates by using an OX API key.

If installation completes but no activity appears in the VibeSec dashboard, see [Troubleshooting VibeSec Installation](/vibesec/installing-vibesec/troubleshooting-vibesec-installation.md).

## What the installation script does

When you run the installation script, it:

1. Downloads a standalone Node.js runtime into `~/.ox/node/`. A system-wide Node.js installation isn't required.
2. Downloads the VibeSec installation package from your on-premises OX platform.
3. Installs the VibeSec hooks for the selected IDE.
4. Registers the hooks in the IDE configuration.
5. Stores the API key and the on-premises OX platform URL in `~/.<ide>/.ox.json`.

## Prerequisites

Before you begin, make sure you have the following:

| Requirement     | Description                                                                                                                                                                  |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OX platform URL | The URL of your on-premises OX deployment, for example `https://ox.yourcompany.com`.                                                                                         |
| OX account      | An account with permission to generate API keys.                                                                                                                             |
| Network access  | Access to your on-premises OX platform, `nodejs.org`, and `ox-vibesec.s3.eu-west-1.amazonaws.com`.                                                                           |
| TLS certificate | The on-premises OX platform URL must be served with a valid, unexpired TLS certificate that the developer's machine can validate. See [TLS certificates](#tls-certificates). |

## TLS certificates

VibeSec connects to your on-premises OX platform URL over HTTPS to download the VibeSec package, check for updates, and report activity. Each machine where VibeSec is installed must trust and be able to validate the TLS certificate used by the OX platform URL.

Use a certificate that your developer machines already trust. The certificate can be issued by a publicly trusted Certificate Authority (CA) or by your organization's internal CA.

Make sure that the certificate:

* Is not expired.
* Includes the OX platform URL in its subject or Subject Alternative Name (SAN).

If you use an internal or private CA, distribute the CA root certificate and any required intermediate certificates to each machine where VibeSec is installed.

**To configure the trusted certificates:**

1. Add the certificates to the appropriate system trust store:
   * **Windows:** Local Machine > Trusted Root Certification Authorities
   * **macOS:** System keychain, with the certificate marked as trusted.
   * **Linux:** Copy the certificate to `/usr/local/share/ca-certificates/`, and then run:

     ```bash
     sudo update-ca-certificates
     ```
2. If the machine trust store is centrally managed and cannot be modified, set the `NODE_EXTRA_CA_CERTS` environment variable to the full path of a PEM file containing the CA chain.
3. Restart the AI coding tool.

For managed fleets, you can distribute the certificates through MDM or group policy as part of the VibeSec deployment. VibeSec uses the machine trust store, so no additional VibeSec configuration is required when the certificates are installed there.

Certificate issuance and renewal are managed by your organization, typically on the reverse proxy or ingress that serves the OX platform URL. OX does not manage TLS certificates for on-premises deployments.

## [Step 1: Generate an API key](/vibesec/installing-vibesec/creating-new-vibesec-tokens.md)

## Step 2: Install VibeSec

Run the installation command for your operating system.

The installation script supports the following parameters:

| Parameter      | Description                                                                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `<IDE>`        | The IDE to install VibeSec for. Supported values are `claude`, `cursor`, and `copilot`. Omit this parameter to install VibeSec for all supported IDEs. |
| `<ONPREM_URL>` | The URL of your on-premises OX deployment, for example `https://ox.yourcompany.com`.                                                                   |
| `<API_TOKEN>`  | The API key secret generated in Step 1.                                                                                                                |

> **Important:** Verify that the `--base-url` parameter points to your on-premises OX platform. If the parameter is omitted or contains an invalid value, the installation script connects to the default OX SaaS environment instead.

### macOS or Linux

Install VibeSec for a specific IDE.

```bash
curl -fsSL https://ox-vibesec.s3.eu-west-1.amazonaws.com/vibesec-installation/install.sh \
  | bash -s -- --ide <IDE> --base-url <ONPREM_URL> --token <API_TOKEN>
```

Install VibeSec for all supported IDEs.

```bash
curl -fsSL https://ox-vibesec.s3.eu-west-1.amazonaws.com/vibesec-installation/install.sh \
  | bash -s -- --base-url <ONPREM_URL> --token <API_TOKEN>
```

### Windows (PowerShell)

Install VibeSec for a specific IDE.

```powershell
& ([scriptblock]::Create((irm https://ox-vibesec.s3.eu-west-1.amazonaws.com/vibesec-installation/install.ps1))) `
  -Ide <IDE> -BaseUrl <ONPREM_URL> -Token <API_TOKEN>
```

Install VibeSec for all supported IDEs.

```powershell
& ([scriptblock]::Create((irm https://ox-vibesec.s3.eu-west-1.amazonaws.com/vibesec-installation/install.ps1))) `
  -BaseUrl <ONPREM_URL> -Token <API_TOKEN>
```

## Uninstall VibeSec

### macOS or Linux

1. Download the uninstallation script.

```bash
curl -fsSL https://ox-vibesec.s3.eu-west-1.amazonaws.com/vibesec-installation/uninstall_ox_hooks.js \
  -o /tmp/uninstall_ox_hooks.js
```

2. Locate the Node.js runtime that VibeSec installed.

```
OX_NODE=$(ls -d ~/.ox/node/v*/bin/node | tail -1)
```

3. Remove VibeSec from all supported IDEs.

```
"$OX_NODE" /tmp/uninstall_ox_hooks.js
```

4. Remove VibeSec from a specific IDE.

```
"$OX_NODE" /tmp/uninstall_ox_hooks.js --ide <IDE>
```

Where `<IDE>` is one of the following:

* `claude`
* `cursor`
* `copilot`

### Windows (PowerShell)

1. Download the uninstallation script.

```powershell
$uninstallPath = Join-Path $env:TEMP "uninstall_ox_hooks.js"

Invoke-WebRequest `
  -Uri "https://ox-vibesec.s3.eu-west-1.amazonaws.com/vibesec-installation/uninstall_ox_hooks.js" `
  -OutFile $uninstallPath -UseBasicParsing
```

2. Locate the Node.js runtime that VibeSec installed.

```
$oxNode = (Get-ChildItem "$env:USERPROFILE\.ox\node\v*\node.exe" | Sort-Object Name | Select-Object -Last 1).FullName
```

3. Remove VibeSec from all supported IDEs.

```
& $oxNode $uninstallPath
```

4. Remove VibeSec from a specific IDE.

```
& $oxNode $uninstallPath --ide <IDE>
```

Where `<IDE>` is one of the following:

* `claude`
* `cursor`
* `copilot`

> **Note:** If multiple Node.js versions are installed under `~/.ox/node`, the commands use the most recently installed version. You can use any installed version to run the uninstall script.


---

# 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-vibesec-on-premises.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.