Getting Started

Installing Gremlin on Windows

Note for Reliability Management (RM) users
Windows is not supported for Reliability Management.

Note for Azure users
If you're installing Gremlin on an Azure Windows instance, be aware that Azure may throttle disk I/O such that large disk experiments will take an excessive amount of time to complete.

General steps for deploying the Gremlin Agent on Windows:

  1. Gather your credentials
  2. Install the Gremlin agent
  3. Configure Gremlin
  4. Validate the installation

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:

  1. Access the Team Settings page in the Gremlin web app.
  2. Click the Configuration tab.
  3. On the Client Configuration File line, click Download to download the file. You'll receive a file named <span class="code-class-custom">config.yaml</span>.
  4. Optionally, make any additional configurations to the <span class="code-class-custom">config.yaml file</span>.

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:


msiexec /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:


msiexec /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:

  1. 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.
    Copy-Item "config.yaml" -Destination "C:\ProgramData\Gremlin\Agent\config.yaml"
  2. Restart the gremlind service:
    Restart-Service -Name gremlind

Validate the installation

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

  1. Check the Agents list in the Gremlin web app
  2. Check the Agent's connection to Gremlin's servers

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:


Get-Service gremlind

This should return the following:

Status   Name               DisplayName
------   ----               -----------
Running  gremlind           Gremlin Daemon

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


Restart-Service -Name gremlind

After verifying that the Gremlin Agent is running, use <span class="code-class-custom">gremlin check auth</span> to check the Gremlin Agent's authentication status:


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

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

Auth Input Type                      : Certificate
API Response                         : OK

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

Auth Input Type                      : No valid auth found
========= Identification ============:
Team ID Source                       : Team ID not found
Gremlin Identifier                   : [Host identifier]
Gremlin Identifier Source            : Not supplied explicitly, using the default
========= Secret/Token Info =========:
Team Secret Source                   : Team Secret not found
.credentials valid                   : /var/lib/gremlin/.credentials file not found
========= Certificate Info ==========:
Team Certificate Source              : Team Certificate not found
========= Private Key Info ==========:
Team Private Key Source              : Team Private Key not found


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:


Uninstall-Package -Name 'Gremlin Agent'
No items found.
This is some text inside of a div block.
Installing the Gremlin Agent
Authenticating the Gremlin Agent
Configuring the Gremlin Agent
Managing the Gremlin Agent
User Management
Health Checks
Command Line Interface
Updating Gremlin
Quick Start Guide
Services and Dependencies
Detected Risks
Reliability Tests
Reliability Score
Deploying Failure Flags on AWS Lambda
Deploying Failure Flags on AWS ECS
Deploying Failure Flags on Kubernetes
Classes, methods, & attributes
API Keys
Container security
Additional Configuration for Helm
Amazon CloudWatch Health Check
AppDynamics Health Check
Blackhole Experiment
CPU Experiment
Certificate Expiry
Custom Health Check
Custom Load Generator
DNS Experiment
Datadog Health Check
Disk Experiment
Dynatrace Health Check
Grafana Cloud Health Check
Grafana Cloud K6
IO Experiment
Install Gremlin on Kubernetes manually
Install Gremlin on OpenShift 4
Installing Gremlin on AWS - Configuring your VPC
Installing Gremlin on Kubernetes with Helm
Installing Gremlin on Windows
Installing Gremlin on a virtual machine
Installing the Failure Flags SDK
Latency Experiment
Memory Experiment
Network Tags
New Relic Health Check
Packet Loss Attack
PagerDuty Health Check
Preview: Gremlin in Kubernetes Restricted Networks
Private Network Integration Agent
Process Collection
Process Killer Experiment
Prometheus Health Check
Configuring Role Based Access Control (RBAC)
Running Failure Flags experiments
Scheduling Scenarios
Shared Scenarios
Shutdown Experiment
Managing Teams
Time Travel Experiment
Troubleshooting Gremlin on OpenShift
User Authentication via SAML and Okta
Managing Users
Integration Agent for Linux
Test Suites
Restricting Testing Times
Process Exhaustion Experiment
Enabling DNS collection
Authenticating Users with Microsoft Entra ID (Azure Active Directory) via SAML