Search documentation
Dashboard
Getting Started

Installing Gremlin on Windows

General steps for deploying the Gremlin Agent on Windows:

Gather your credentials

All Gremlin integration installations require authentication with the Gremlin Control Plane. We recommend using the Client Configuration File method, as it contains everything needed to authenticate and configure the Gremlin Agent in one file. To create and download a client configuration file:

  • Access the Team Settings page in the Gremlin web app.
  • Click the Configuration tab.
  • On the Client Configuration File line, click Download to download the file. You'll receive a file named config.yaml.
  • Optionally, make any additional configurations to the config.yaml file.

If you wish to use another method of authenticating, see the Authentication docs.

Install the Gremlin Agent

Run the following from an elevated command prompt and continue through the installation wizard:

PowerShell
1msiexec /package https://windows.gremlin.com/installer/latest/gremlin_installer.msi

To automate the installation (e.g. for auto-deploying Gremlin onto new instances), use the following command:

Powershell
1msiexec /quiet /package https://windows.gremlin.com/installer/latest/gremlin_installer.msi

Configure Gremlin

The minimum configuration required to authenticate the Gremlin Agent is:

  • Team ID
  • Secret or certificate

If you downloaded a client configuration file, you already have everything needed to register the Agent. Just follow these instructions:

  • Copy the configuration file (named config.yaml) to the C:\ProgramData\Gremlin\Agent directory. The final path should be C:\ProgramData\Gremlin\Agent\config.yaml.

    PowerShell
    1Copy-Item "config.yaml" -Destination "C:\ProgramData\Gremlin\Agent\config.yaml"

  • Restart the gremlind service:

    PowerShell
    1Restart-Service -Name gremlind

Validate the installation

There are two ways to ensure your installation was successful and your Agents authenticated successfully:

Check the Gremlin web app

The easiest way to verify connectivity is to open the Agents list in the Gremlin web app. Check for your newly installed Agent by name or by tag. You can also use the search box to search by name or tag, Agent version, operating system (OS), or region. If your Agent does not appear in this list, it may not have been installed or configured correctly, or it might not be able to reach Gremlin's servers.

Check the Gremlin Agent

First, verify that the Gremlin Agent is running on the target system:

PowerShell
1Get-Service gremlind

This should return the following:

1Status   Name               DisplayName
2------   ----               -----------
3Running  gremlind           Gremlin Daemon

If the service is instead reporting as inactive or failed, try restarting the service using:

PowerShell
1Restart-Service -Name gremlind

After verifying that the Gremlin Agent is running, use gremlin check auth to check the Gremlin Agent's authentication status:

shell
1& 'C:\Program Files\Gremlin\Agent\gremlin.exe' check auth

If the Gremlin Agent authenticated successfully, the output will be similar to the following:

1auth
2====================================================
3Auth Input Type                      : Certificate
4API Response                         : OK

If not, the output will explain why the Gremlin Agent was unable to authenticate:

1auth
2====================================================
3Auth Input Type                      : No valid auth found
4========= Identification ============:
5Team ID Source                       : Team ID not found
6Gremlin Identifier                   : [Host identifier]
7Gremlin Identifier Source            : Not supplied explicitly, using the default
8========= Secret/Token Info =========:
9Team Secret Source                   : Team Secret not found
10.credentials valid                   : /var/lib/gremlin/.credentials file not found
11========= Certificate Info ==========:
12Team Certificate Source              : Team Certificate not found
13========= Private Key Info ==========:
14Team Private Key Source              : Team Private Key not found

Troubleshooting

If the Agent is connected but is reporting as unhealthy, see Troubleshooting Unhealthy State in the Gremlin Knowledge Base. If you're having trouble authenticating, see the Authentication FAQ in the Gremlin Knowledge Base for possible causes and solutions.

Uninstalling Gremlin from Windows

To uninstall the Gremlin Windows agent, run the following PowerShell command from an elevated command prompt:

powershell
1Uninstall-Package -Name 'Gremlin Agent'