Introducing Flood Agent: standalone infrastructure for load testing

Originally posted here.

Working from home during this pandemic and wondering how to start load tests from the office? Today, we’re officially introducing Flood Agent, a way to turn your own physical or virtual machines into load generators that you can control from anywhere with an internet connection.


  • Installing Flood Agent on a machine lets you start load tests on it remotely from Flood—even if it’s within a corporate VPN.
  • Flood Agent is a simple binary that you can install on Linux, macOS, and Windows machines.
  • Once you’ve installed Flood Agent, your machines show up on the Flood web app to use as load generators or grids.

Boldly going where no one has gone before

Load testing within your company’s VPN and trying to coordinate it from home is like being on a maintenance pod trying to contact your starship, but a Mazarite ship is broadcasting a jamming signal, so comms are down. That Mazarite ship is your company’s firewall, and it can make testing difficult.

The easiest way around this is to provision load generators in the cloud. However, because your application servers are still behind a firewall, you’d need to convince IT security to whitelist the IP addresses of the load generators. Depending on how tight security policies are, this may not be an option even in this new world of remote working.

Flood Agent is a way to start load tests on Flood from the load generators you already have. It’s a cross-platform agent that you can install on your regular load generators, allowing you to control them on Flood.


Flood Agent is kind of like the Borg Collective. Each machine that you install Flood Agent on is assimilated into the Borg. A hive mind (you, on the Flood site) controls all Borgs, coordinating test execution with robotic efficiency.

Check out this video to follow along as I walk you through the process of setting up Flood Agent, or you can keep reading for the text version.

Installing and configuring Flood Agent

Flood Agent is a free binary, and it runs on Linux, Mac, or Windows machines. You can download the appropriate version for your operating system and then follow the installation instructions here for more information:

Getting started on Linux

Getting started on macOS

Getting started on Windows

After installing Flood Agent, you can configure it according to how you want to use it. Start Flood Agent in your terminal and use the configure functionality. Here’s what that command looks like on macOS, but you can follow the links above for other operating systems:

./flood-agent configure

Linking your Flood account

The command above yields a prompt for a token like this:

This token allows Flood to run load tests on the load generator that you’ve installed Flood Agent in. To get the token, go to the API Access page on your Flood account (you already have one, don’t you?) and click REVEAL token.

You should see a string of characters like this:

Copy your token (anything after the = sign) and paste it into the Flood Agent terminal window.

Choosing load testing tools

Next, you can choose which tools you’d like to set up and which version of those tools Flood Agent uses to run your tests.

Starting with JMeter, Flood Agent asks you which of the tools you’d like to configure. You can choose to set up your tools at the beginning so that you don’t have to set them up again, or you can go back to this configuration wizard at any point to add another tool. Either way, you need to provide the tools that you select in one of two ways: via a Docker image supplied by Flood, or via a local installation that you already have.

For this example, I chose to configure JMeter and to use a local installation. Local installations give you the most flexibility because you can use the version of the tool that you prefer, along with any special plugins. However, if you already have Docker installed or don’t want to manually install JMeter separately, you can also use our Docker image for JMeter.

Selecting a local installation prompts you to provide the location of that directory:

For JMeter, this looks something like /Users/nvanderhoeven/jmeter/apache-jmeter-5.1.1.

After you enter this file path, Flood Agent checks to make sure the directory is valid. You can also set the configuration for other tools in this dialog.

After you finish the configuration, the wizard writes to a config.yaml file in your Flood Agent directory. You can also edit this configuration file directly in the future if you prefer.

Verifying Flood Agent configuration

To run a final check on whether Flood Agent has been installed correctly, type ./flood-agent check. You should see a summary of the configuration options you selected as well as some connectivity and validity checks, like this:

These green check marks mean you’re good to go! If you’re running Flood Agent from within a corporate network, though, you may see some errors here.

Troubleshooting network connectivity within a corporate network

If your company already has a web proxy, check out our guide on running floods through this proxy.

Please ensure that the load generator that you’ve installed Flood Agent on has access to the following endpoints:


You may need to request these from your IT department.

If you get stuck, please contact us at We’d love to go over your specific situation and get you up and running.

Once Flood Agent returns a successful check, you can start up your own grid!

Turning your machine into a Flood grid

A grid, in Flood terminology, is a group of machines to be used for load generation. To make your machine a grid, run this command:

./flood-agent --grid askaflooder

where askaflooder is the name of your grid.

Once you see those [agent] ready and awaiting next job messages, you’re ready to run your test!

Running a load test on your own infrastructure

Log into your account on Flood, if you aren’t already, and create a new stream like you normally would, uploading your load testing script and data files. When launching your test, though, select the option for Hosted infrastructure and then choose the grid with Flood Agent running on it.

Go ahead and launch your test. Congratulations, you’re now set up to run a load test on your on-premise load generators!

Giving it a go

Flood Agent is a free download, so you’ll only need to pay when you run load tests on Flood. However, we also have a free tier— perfect for a proof-of-concept while you’re working from home.

If you have any questions about Flood Agent, check out our documentation or email us. We’d be happy to get you started!

Download Flood Agent for free here.

See Also