Guide · Open source

How to use Toxiproxy: install, populate and test failures

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Toxiproxy is an open-source TCP proxy from Shopify that sits between your application and the services it depends on, such as databases and caches. It is built for testing, CI and development environments, where you route connections through it and then add latency, cut connections or limit bandwidth through a simple HTTP API. After this guide you will know how to install it, register proxies, and use them to check whether your application handles failures gracefully.

ToxiproxyShopify/toxiproxy · ★ 12.5k · MIT Install options & downloads

Quick start

1Install Toxiproxy. Install the server with Homebrew on macOS, pull the Docker image, or build from source with make build if you have Go installed.
2Start the server. Run the toxiproxy-server binary, or start the Docker container, so the HTTP API is available.
3Populate proxies. Register each service with a name, a listen address your app will use, and the upstream address of the real service.
4Point your app at the proxy. Configure your test environment so its connections go to the listen address instead of the real service.
5Add a toxic. Apply a toxic such as latency or down to the proxy, using the client library for your language.
6Assert the behaviour. Run your test and check that your application handles the failure, such as returning a fallback value instead of raising an error.

What Toxiproxy does and when to use it

Toxiproxy is a framework for simulating network conditions. It is made for testing, CI and development environments and supports deterministic tampering with connections, as well as randomized chaos and customization.

It has two parts: a TCP proxy written in Go, which is what the repository contains, and a client that talks to the proxy over HTTP. You configure your application so that its test connections go through Toxiproxy, then change their health over HTTP.

Use it to test whether your app copes when a database or cache is down.
Use it to check how your app behaves under added latency or slow connections.
Do not use it for production traffic, since the README positions it for testing, CI and development.

How do you install Toxiproxy?

The README lists package-manager installs for macOS and Docker. On macOS you can use Homebrew. The Docker image is published on the GitHub container registry. Binaries and system packages for Linux and Windows are on the project's Releases page. The README lists no prerequisites for the package-manager and Docker routes.

If you have Go installed, you can build Toxiproxy from source with the make file. The README also lists MacPorts and an Ubuntu .deb package.

Homebrew (macOS): brew tap shopify/shopify, then brew install toxiproxy.
Docker: pull the image, then run it. Use --net=host if you call Toxiproxy from the host rather than from another container.
Windows: download the server and CLI executables from the Releases page.
Source: with Go installed, run make build, then start ./dist/toxiproxy-server.

$ brew tap shopify/shopify
$ brew install toxiproxy

$ docker pull ghcr.io/shopify/toxiproxy
$ docker run --rm -it ghcr.io/shopify/toxiproxy

How do you populate Toxiproxy with proxies?

Before any connection is made, register each service you want to test as a proxy. Each proxy has a name, a listen address that your application connects to, and an upstream address for the real service. In the README's Ruby example this is done once in config/boot.rb with Toxiproxy.populate.

Then point your application's client at the listen address instead of the real service. In the README example the Redis client connects to port 22222 instead of 6379.

name: a label you use to find the proxy later.
listen: the address your application connects to, such as 127.0.0.1:22222.
upstream: the real service, such as 127.0.0.1:6379.

require 'toxiproxy'

Toxiproxy.populate([
  {
    name: 'toxiproxy_test_redis_tags',
    listen: '127.0.0.1:22222',
    upstream: '127.0.0.1:6379'
  }
])

How do you add failures with toxics?

Once traffic flows through a proxy, you add a toxic to change its behaviour. The README's Ruby client applies a toxic for the duration of a block and removes it afterwards. The examples below use the Ruby client; the README notes that you can write a client in any other language.

A latency toxic adds delay to the traffic. A down toxic takes down all matching proxies, so the code inside the block gets a connection error.

Toxiproxy[:mysql_master].downstream(:latency, latency: 1000).apply do
  Shop.first
end

Toxiproxy[/redis/].down do
  Shop.first
end

Which toxics does Toxiproxy support?

The README's table of contents lists nine toxics: latency, down, bandwidth, slow_close, timeout, reset_peer, slicer, limit_data and packet_loss. The README documents each one in its Toxics section, and the HTTP API section lists the proxy and toxic fields you send.

Start with latency and down, since they cover the most common failure tests.

latency: adds delay.
down: takes the proxy down.
bandwidth: limits bandwidth.
slow_close, timeout, reset_peer, slicer, limit_data and packet_loss: further connection behaviours described in the README.

How do you write a test that checks graceful failure?

The README's example stores post tags in Redis. The test takes Redis down through Toxiproxy and asserts that listing tags returns an empty array instead of raising an error. Before the fix, the test fails with Redis::CannotConnectError. After the code rescues that error and returns an empty array, the test passes.

The README suggests a unit test for this and, for full coverage, an integration test that loads the whole page while Redis is down.

Write the failing test first, using a down toxic on the Redis proxy.
Fix the code so it rescues the connection error and returns a safe default.
Re-run the test to confirm the fallback works.

test "should return empty array when tag redis is down when listing tags" do
  @post.add_tag "mammals"

  Toxiproxy[/redis/].down do
    assert_equal [], @post.tags
  end
end

What people use it for

Test that a web page still renders when its Redis tag store is down.
Check how a service behaves when a MySQL query takes an extra second.
Run failure tests in CI on a machine where Linux tools like nc are not available or need root.
Simulate slow connections to see whether timeouts in your app are set sensibly.

Frequently asked questions

How do I install Toxiproxy?

On macOS, run brew tap shopify/shopify and then brew install toxiproxy. You can also pull the Docker image with docker pull ghcr.io/shopify/toxiproxy, or download binaries from the Releases page. The README also describes building from source with make build if you have Go installed.

Is Toxiproxy free to use?

Yes. The repository is licensed under the MIT licence. The README lists no price for the project.

What are the requirements for Toxiproxy?

The README lists no prerequisites for the install methods it describes. Building from source requires Go. Your application's language needs a client, and the README lists clients for several languages, or you can write your own.

What are the alternatives to Toxiproxy?

The comparable projects listed are Chaos Mesh, Pumba and Comcast. The README's stated reason for Toxiproxy is its dynamic API for integration and unit testing, and that Linux tools like nc are not cross-platform and require root.

Can I use Toxiproxy in production?

The README positions Toxiproxy for testing, CI and development environments, not production traffic management. Use it to prove your application handles failures in those environments.

Why did my client stop working after upgrading Toxiproxy?

The README says the 2.0 API changes are not compatible with 1.x. To use the 2.x server, your client library must support the same version, so check that before you upgrade.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Toxiproxy suits engineers who need to test how an application behaves when a database, cache or network link fails or slows, especially in CI and on machines without root access. It is not meant for production traffic, and it does not help if your services do not talk over TCP. If you need a chaos tool for a Kubernetes cluster, the comparable projects Chaos Mesh, Pumba and Comcast are worth comparing.

Install options & downloads