Getting Started

Installing Gremlin on a virtual machine

Before installing, review the list of caveats to see if additional steps are required for your environment.

General steps for deploying the Gremlin Agent to a virtual machine:

  1. Gather your credentials
  2. Install Gremlin packages
  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 Gremlin packages

Choose the format that corresponds to your distribution.

If you intend to run experiments against container workloads, it is recommended to install Gremlin as a container using the Docker image. If you choose to install Gremlin using an RPM or DEB package and target container workloads with experiments, some work may be necessary to grant the gremlin Linux user access to container socket files such as /run/containerd/containerd.sock . By default, Gremlin will add itself to the docker Linux group if it is present during installation.

DEB packages

For DEB-based Linux distributions such as Ubuntu, Debian, and so on.


# Add packages needed to install and verify gremlin (already on many systems)
sudo apt update && sudo apt install -y apt-transport-https dirmngr

# Add the Gremlin repo
echo "deb https://deb.gremlin.com/ release non-free" | sudo tee /etc/apt/sources.list.d/gremlin.list

# Import the GPG key
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 9CDB294B29A5B1E2E00C24C022E8EF3461A50EF6

# Install Gremlin
sudo apt update && sudo apt install -y gremlin gremlind

Installing older versions
If you want to install an older version of Gremlin, you can list all Agent versions using apt list -a gremlin and install them using apt install gremlin-x.x.x-x

RPM packages

SUSE-based distributions

For distributions based on SUSE Linux, such as SUSE Linux Enterprise Server (SLES), openSUSE, etc.:


# Install dependencies
sudo zypper install -y iproute-tc libcap-progs

# Add the Gremlin repo
curl https://rpm.gremlin.com/gremlin.repo -o /tmp/gremlin.repo && sudo zypper addrepo /tmp/gremlin.repo

# Install Gremlin and dependencies
sudo zypper refresh && sudo zypper install gremlin gremlind

Non SUSE-based distributions

For non SUSE-based RPM distributions such as Amazon Linux, RHEL, CentOS, etc.:


# Install dependencies
sudo yum install -y iproute-tc

# Add the Gremlin repo
sudo curl https://rpm.gremlin.com/gremlin.repo -o /etc/yum.repos.d/gremlin.repo

# Install Gremlin
sudo yum install -y gremlin gremlind

If you're using RHEL 8, the following packages must be installed:iproute-tc


sudo yum install -y iproute-tc kernel-modules-extra

If you're using RHEL 9, the following packages must be installed:

Fresh deployments of RHEL 9 may require a reboot for the necessary kernel module to be load, as the packages pulls in an updated kernel-core package.


sudo yum install -y iproute-tc kernel-modules-extra

Installing older versions
If you want to install an older version of Gremlin, you can list all Agent versions using yum list available gremlin --showduplicates and install them using yum install gremlin-x.x.x-x

Docker image

Alternatively, instead of installing Gremlin directly on the host operating system, you can deploy Gremlin from the Docker image on DockerHub.

To run the daemon, use the following command. Replace <span class="code-class-custom">$GREMLIN_TEAM_ID</span> with your team ID and <span class="code-class-custom">$GREMLIN_TEAM_SECRET</span> with your team's secret key:


docker run -d \
    --net=host \
    --pid=host \
    --cap-add=SYS_PTRACE \
    --cap-add=SYS_ADMIN \
    --cap-add=SYS_CHROOT \
    --cap-add=SYS_RESOURCE \
    --cap-add=NET_ADMIN \
    --cap-add=SYS_BOOT \
    --cap-add=SYS_TIME \
    --cap-add=KILL \
    -v /var/lib/gremlin:/var/lib/gremlin \
    -v /var/log/gremlin:/var/log/gremlin \
    -v /sys/fs/cgroup:/sys/fs/cgroup \
    -v /var/run/docker.sock:/var/run/docker.sock \
    gremlin/gremlin daemon

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 /etc/gremlin/ directory. The final path should be /etc/gremlin/config.yaml:
    sudo cp config.yaml /etc/gremlin/config.yaml
  2. Restart the gremlind service
    sudo systemctl restart gremlind

Additional configuration options

Read this section if you wish to further configure the Gremlin Agent. Otherwise, skip to the next section.

For Reliability Management, Gremlin uses tags such as operating system, zone, and local-hostname to identify each service's fingerprint. Gremlin automatically detects many tags, but if you wish to apply custom tags (e.g. environment, location, or service name), read the Network tags documentation.

For more information and additional configuration options, see Configuring Gremlin for more information.

Make any edits to the <span class="code-class-custom">/etc/gremlin/config.yaml file</span>, then restart the <span class="code-class-custom">gremlind</span> service after you've made your changes.

Customize Gremlin's Linux user and group

By default on Linux, Gremlin installs a gremlin Linux user and group, and sets the suid bit on /usr/bin/gremlin so that all users can run the Gremlin executable. These defaults can be overridden at installation time by supplying environment variables to the installer.

For example, to run Gremlin as root and restrict executable access to <span class="code-class-custom">root:root</span>, you would run:


  sudo -E yum install gremlin gremlind

The full list of variables available at install time, and their defaults are as follows:

GREMLIN_INSTALL_USERgremlinThe Linux user to own all file installed by Gremlin. This user is created if it does not exist
GREMLIN_INSTALL_GROUPgremlinThe Linux group to own all file installed by Gremlin. This group is created if it does not exist
GREMLIN_INSTALL_BIN_MODE0750*The file mode for executable files installed by Gremlin.
GREMLIN_INSTALL_BIN_CAPABILITIESunsetA boolean argument specifying whether Gremlin's required capabilities should be set on the binaries themselves. The default is false. Any value supplied to this variable evaluates to true.

* Gremlin versions before <span class="code-class-custom">2.33.0</span> default this value to <span class="code-class-custom">6111</span> instead.

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:


sudo systemctl status gremlind

This should return the following:

● gremlind.service - Gremlin Daemon
     Loaded: loaded (/etc/systemd/system/gremlind.service; enabled; vendor preset: enabled)
     Active: active (running) since Wed 2023-01-04 10:44:12 EST; 5 days ago

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


sudo systemctl restart 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:


gremlin 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 Troublehsooting 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 a virtual machine

The command for uninstalling the Gremlin agent from a Linux virtual machine will vary depending on your distribution.

Uninstalling DEB packages

For DEB-based Linux distributions such as Ubuntu and Debian:


sudo apt remove gremlin gremlind

Uninstalling RPM packages

SUSE-based distributions

For distributions based on SUSE Linux, such as SUSE Linux Enterprise Server (SLES), openSUSE, etc.:


sudo zypper remove gremlin gremlind

Non SUSE-based distributions

For non SUSE-based RPM distributions such as Amazon Linux, RHEL, CentOS, etc.:


sudo yum remove gremlin gremlind

Uninstalling Docker image

If you deployed Gremlin using Docker, use the following command to uninstall it. Note that the container name may be different than <span class="code-class-custom">gremlin</span>, depending on whether you specified a name:


sudo docker stop gremlin
sudo docker rm gremlin
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
Health Checks
Command Line Interface
Updating Gremlin
Reliability Management (RM) 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
Time Travel Experiment
Troubleshooting Gremlin on OpenShift
User Authentication via SAML and Okta
Managing Users and Teams
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
AWS Quick Start Guide
Installing Gremlin on Amazon ECS
Experiments Revamp