Agent Installation Fails

Last updated: December 19, 2025

This article explains how to diagnose and resolve issues where the Cyrisma agent fails to install on an agent host.

Symptoms

  • Installer does not complete or exits unexpectedly

  • Installation returns permission or access denied errors

  • Agent service is not created after installation

  • Installer completes but the agent does not start

Common Causes

  • Installer not executed with sufficient privileges

  • Required operating system prerequisites are missing

  • Endpoint protection or application control blocks agent components

Diagnostic Steps

Follow the steps below in order. Do not skip steps.

1. Confirm Administrative Privileges

Agent installation requires elevated privileges.

What to check

  • Ensure the installer is executed with administrative or root privileges

  • On Windows, run the installer as an administrator

  • On macOS and Linux, run the installer using elevated permissions

If the installer was not run with sufficient privileges, rerun the installation with the appropriate permissions.

2. Verify Operating System Prerequisites

The agent will fail to install if required OS components are missing.

What to check

  • Windows

    • .NET Framework 4.8 or later is installed

  • macOS

    • Full Disk Access is granted to the installer

  • Linux

    • Required dependencies are installed, including:

      • python3

      • pip

      • ping3

      • pysmb

3. Check Endpoint Protection and Application Controls

Endpoint protection tools may block agent installation components.

What to check

  • Antivirus, EDR, or application control logs

  • Quarantine or block events related to agent files or scripts

If blocks are identified, apply appropriate exclusions and retry installation.

4. Review Installation Logs

Installation logs provide details when installation fails.

Log locations

  • Windows:
    C:\Cyrisma_Agent\logs\Cyrisma_Agent_Install.log

  • macOS:
    /var/log/install.log

  • Linux:
    /var/log/syslog

Review logs for permission errors, blocked execution, or missing dependencies.

Resolution

Most installation failures are resolved by one or more of the following actions:

  • Re-running the installer with elevated privileges

  • Installing missing operating system prerequisites

  • Configuring endpoint protection to allow agent installation

After corrective actions are taken, rerun the installer and confirm the agent service starts successfully.

When to Contact Support

Contact Cyrisma Support if:

  • Installation continues to fail after completing all diagnostic steps

  • Logs indicate repeated or unresolved installation errors

Provide:

  • Agent host operating system and version

  • Relevant installation log files

  • A summary of steps already performed