> 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/troubleshooting-vibesec-installation.md). # Troubleshooting VibeSec Installation ## About VibeSec installation troubleshooting Use this page to troubleshoot VibeSec installation issues when the installation completes successfully, but VibeSec activity does not appear in OX. ## Installation succeeds, but no activity appears in OX After installing VibeSec, you might experience one or more of the following: * The installation script completes without errors, and your AI coding tool shows that the VibeSec hooks are installed. * The VibeSec page in OX continues to display the installation prompt. * The Agent Activity Log remains empty after you send prompts in your AI coding tool. ## Check the VibeSec log VibeSec writes activity and connection information to a local `debug.log` file. You can use this log to verify whether VibeSec can communicate with the OX platform. The log is available in the following locations: | Log | Location | | ------------------ | ------------------------ | | Shared log | `~/.ox/debug.log` | | AI coding tool log | `~//.ox/debug.log` | For the AI coding tool log, replace `` with `claude`, `cursor`, `copilot`, or `kiro`. On Windows, `~` represents `%USERPROFILE%`. For example: ``` C:\Users\\.ox\debug.log ``` ### TLS certificate validation errors If `debug.log` contains a certificate error, the machine cannot validate the certificate presented for the OX platform URL. For example: ``` 2026-08-11T09:59:21.506Z | system | UPDATER | Fetching version from https://ox.example.com/api/ai-agent-service 2026-08-11T09:59:21.707Z | system | UPDATER | Update failed: self-signed certificate in certificate chain ``` The log might contain one of the following errors: * `self-signed certificate in certificate chain` * `unable to verify the first certificate` * `unable to get local issuer certificate` * `SELF_SIGNED_CERT_IN_CHAIN` * `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` * `certificate has expired` These errors can occur when: * Your organization inspects outbound HTTPS traffic by using TLS inspection, an HTTPS proxy, or a SASE/CASB endpoint agent, and the inspection CA is not available in the machine trust store. * Your on-premises OX platform uses a certificate issued by an internal or private CA. For more information, see \[Installing VibeSec On-Premises]. * The certificate presented for the OX platform URL has expired. ### Resolve TLS certificate validation errors To restore communication between VibeSec and the OX platform, make sure that your machine trusts the CA that signs the HTTPS traffic. **To resolve a TLS certificate validation error:** 1. Make sure VibeSec is up to date. Reinstall VibeSec or allow the VibeSec hooks to update automatically, and then retry the connection. Support for using the machine trust store was added in the September 2026 release. 2. Add the CA root certificate that signs the traffic to the machine trust store. Use the appropriate trust store for your operating system: | Operating 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 `sudo update-ca-certificates` | In managed environments, CA certificates are typically distributed through MDM or group policy. Contact your IT or endpoint team to verify whether the required CA is already deployed to your machine. 3. Restart your AI coding tool. 4. If the machine trust store is centrally managed and cannot be changed, set the `NODE_EXTRA_CA_CERTS` environment variable to the full path of a PEM file that contains the required CA chain. 5. Restart your AI coding tool. 6. Send a prompt in your AI coding tool. 7. Open `debug.log` and verify that the certificate error no longer appears. The activity should also appear in the VibeSec dashboard. If the certificate error persists, contact OX Technical Support and attach the `debug.log` file. --- # 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/troubleshooting-vibesec-installation.md?ask=&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.