Skip to main content

Install the Huntress Agent for Windows OS

Alan
  • Updated

Team: Huntress Managed Endpoint Detection and Response (EDR), Huntress Managed Security Information and Event Management (SIEM)
Environment: Windows
Summary: This guide provides instructions and options for installing the Huntress Agent on Windows endpoints (with links to macOS and Linux agent guides). 

 

In this article

For Other Operating Systems

Before You Begin
     Review Supported Operating Systems and System Requirements    
     Download the Agent Installer from the Web Interface 
     Collect Your Account and Organization Keys

Installation Methods
     Manual Installation from the GUI
     Silent Installation from a Script or Command Line
     Deploy via RMM
     Deploy via PowerShell (Including GPO)

Result
Troubleshooting Installation Issues
 

For Other Operating Systems

For macOS installation, please follow these guides, starting with Critical Steps for Complete macOS EDR Deployment

For Linux installation, please follow these guides. 
 

Before You Begin

Make sure to retrieve your Account Key and Organization Key from the Huntress Platform before starting the installation. You can also define optional Agent Tags for grouping endpoints within an organization.

The Account Key and the installer package for the Huntress Agent is only accessible by Account level users. If you are an organization user, please reach out to your Account admin for assistance installing the Huntress Agent. 

 

Review Supported Operating Systems and System Requirements 

If you have not already, ensure that the endpoint you are attempting to install the Huntress Agent on is supported and meets the necessary system requirements. Some features may not be available on all operating systems. During install, the Huntress Agent will download the appropriate agent for your device (ie: 32 / 64 bit). 

 

Download the Agent Installer from the Web Interface 

This is most commonly used for manual installs, but can be used for other deployment methods as needed.

  1. Log in to Huntress 
  2. Go to the Download Agent page (this page is not visible if you lack install permissions)
  3. Expand the Manual Install section with the View Installation Guides prompt 
  4. Use the Download the installer to download the installer file you need. You can use this page to get the installer for Windows, macOS, and Linux. This will download a HuntressInstaller.exe file for Windows.

If you know your account key already, you can also fetch the installer by browsing to the following URL. Input your account key in place of <acct_key>. 

https://huntress.io/download/<acct_key>/HuntressInstaller.exe

 

Collect Your Account and Organization Keys 

All installs require both of these keys. Please ensure you are using your most recent keys to 

  1. Log in to Huntress 
  2. Go to the Download Agent page (this page is not visible if you lack install permissions)
  3. Expand the desired install section with the View Installation Guides prompt 
  4. Copy your Account key and store it for later use. 
  5. Use the Organization key section to either copy an existing organization's key, or simply type the name of a new organization you wish to create and it will generate a new Organization Key for you. Store this key for later use. 

 

Installation Methods

Once you have the installer file and/or keys you need, proceed to install the Huntress Agent using your desired installation method. 

Manual Installation from the GUI

Silent Install from a Script or Command Line

Deploy via RMM (Remote Monitoring and Management)

Deploy via PowerShell (Including GPO)


Manual Installation from the GUI

This method is best for individual, non-scripted installations.

  1. Double-click the HuntressInstaller.exe file and follow the GUI prompts. 
  2. Enter your Account Key.
  3. For the Organization Key, specify the short name or phrase that uniquely identifies the client or organization this Agent is associated with. Any Agent installed with this same key will be grouped within the same Organization. 
  4. You can optionally specify Tags to group your agents within an organization.

    file-UPm5h138ge.png
  5. Click the Install button to finish your manual installation.

 

Silent Installation from a Script or Command Line

Silent installation is best suited for deployments using an RMM or configuration management solution, as it runs without interrupting end users with pop-ups. The installer supports the following flags:

  • /ACCT_KEY - specify the Account Key (required)
  • /ORG_KEY - specify the Organization Key (required)
  • /S - perform a silent installation (required and must be uppercase) 
  • /TAGS - specify any Tags (optional)

Format of the command:

HuntressInstaller.exe /ACCT_KEY="<Your Account Key>” /ORG_KEY="<Your Organization Key>" /TAGS="<Your Desired Tags>" /S

Example:

HuntressInstaller.exe /ACCT_KEY="fm47t6kjegi83hjgk2wo912jtdg4h0p1" /ORG_KEY="wibble-wobble-bank" /TAGS="human,support" /S

For a single command line to install the Huntress Agent without downloading the file first, please see the guide on Single Command Installation. 


 

Deploy via RMM (Remote Monitoring and Management) 

Huntress provides automated deployment scripts for our partners using the following RMM and deployment software. 

Note that we do not have scripts for all existing RMMs, and updates to existing RMMs may result in incomplete or outdated scripts. While we try to keep these updated, if you run into errors with a script, or notice a document is outdated, please reach out to Huntress support with details. For best results, do not modify scripts unless explicitly directed to do so.

 

Deploy with PowerShell (Including GPO)

Huntress Labs has a GitHub repository with useful scripts. Below is a direct link to instructions on deploying the PowerShell scripts via GPO

Result

Within 15 minutes of install (typically sooner), the newly installed agent should appear in the Huntress portal with the name of the endpoint.

For endpoints that support the Process Insights service or are being used for SIEM, the EDR service (Rio) will complete installation about an hour after the agent completes installing. You can verify it completed in the Agent Overview page with the EDR Version. This is expected behavior. 

Once installation is complete, the Huntress Agent will begin its periodic checks (called a survey) on the endpoint and report back any requested logging to the Huntress Platform. This is an automated process. 


Troubleshooting Installation Issues

Logs detailing potential issues are available for troubleshooting and are a great first source of information about why an agent failed to install or is experiencing issues.

C:\Windows\Temp\HuntressInstaller.log

C:\Program FIles\Huntress\HuntressAgent.log

If you used an RMM or other third party tool, please check your RMM logs directly for errors.


Some common scenarios are detailed below, but are further detailed in our Why Has a New Agent Not Checked In? guide. 

Scenario Possible Situation and Solution
Agent installation failed with “unable to register agent: invalid account secret key” 

Situation: The agent install is failing to register to the Huntress portal due to an incorrect account key 

Solution: Account keys are 32 characters long. When you copy the account key into the installer files, ensure it is exactly 32 characters without any leading or trailing spaces. 
Agent install failed with “ERROR: Installer failed to complete in 120 seconds. Possible interference from a security product?”

Situation: The agent install is failing due to possible interference from third party tools, such as Antivirus or Network Configuration issues

 

Solution: Ensure that the Huntress Agent has been allow listed in all third-party antivirus solutions. Also ensure that the endpoint is not limiting internet access to critical sites used during the install. This may include checking for SSL/TLS Inspection services that are impacting Huntress certificates
Agent install failed with “Script Failed! ERROR: C:\Program Files\Huntress\wyUpdate.exe did not exist.”

Situation: The Huntress agent is attempting to use the legacy wyUpdate.exe file during install instead of the new HuntressUpdater.exe

Solution: The wyUpdate.exe file was used in legacy installations, but is not used during newer installs. If you are receiving this message, you are likely using an older script or installation file. Download the newest install file / script and re-try the install. A clean reinstall may be required. 
Agent install failed with “The Huntress Agent is already installed in C:\Program Files\Huntress. Exiting with no changes.”

Situation: During the Huntress Agent install, a previous install file or directory was detected. This can be seen if a previous installation failed, or if an agent uninstall was recently completed. 

Solution: 

  1. Is the Huntress Agent already installed? Are all three Huntress Agent services running (Huntress Agent, Huntress Updater, and Huntress Rio)? Can you restart them? 
  2. If the services don’t exist, check for signs of previous installation, such as Huntress files or directories. Does the C:\Program Files\Huntress directory already exist? If it is present, delete it, consider rebooting to ensure it is gone, and try the install again. 
  3. Consider re-running the installer with the -reinstall or -reregister flag 
Agent install was successful, but the agent is not in the list of agents under the expected organization.

Situation: The Huntress agent was installed successfully (agent service is running), but does not appear in the Huntress portal where it is expected to be. 

Solution: Often times when an agent appears to be “missing” in the Huntress portal, it is often because:

  1. Installed under the wrong organization. Check for any duplicate or new, unexpected organizations. If the organization key did not match exactly to an existing organization, a new one may have been created during install.
  2. Installed under the wrong account. If you have recently updated or changed your Account Key, or if the agent was previously installed under a different partner account, the account key may not have been updated during install. Check what account key was used and verify it matches what is in your account.
  3. The agent registration process did not complete. If the endpoint goes offline soon after install, the agent may not have had time to complete registration into the Huntress portal. Ensure the endpoint has power and internet for at least 15 minutes after install to ensure it has time to register.
Agent install was successful, but some policies or features are not working as expected (ex: host isolation, Defender policies not applying)

Situation: The Huntress agent was installed successfully (agent service is running), but certain EDR features are not working as intended. The endpoint is domain joined. This is most commonly seen on laptops or devices that do not “check in” to their domain controller regularly. 

Solution: Endpoints joined to an Active Directory domain that are unable to communicate to the domain controller will be unable to set local policies. This includes features like Host Isolation, and some Managed Microsoft Defender policies. Test domain controller connectivity and ensure there are no known issues.

 

Related articles