cloudparts

Toxiproxy

A small TCP proxy from Shopify that sits between your app and a dependency such as MySQL or Redis in tests, and adds latency, timeouts, cut connections or bandwidth limits on command through an HTTP API.

What it is
Chaos engineering
Used for
Automated testing
Type
Open source
Made by
Shopify
License
MIT
Facts checked
24 October 2026
Website Source code

What it is

Toxiproxy is a Go server that you run in development, CI or a test environment. For each dependency you create a proxy with a name, an address to listen on and the upstream address, and point the app’s test configuration at the proxy instead of the real service. Everything then flows through Toxiproxy untouched until a test changes it through the HTTP API on port 8474, either directly, with toxiproxy-cli, or with a client library for Ruby, Go, Python, .NET, PHP, Node.js, Java, Rust, Elixir or Haskell.

Faults are called toxics: latency (with jitter), down, bandwidth, slow_close, timeout, reset_peer, slicer (cuts data into small, delayed pieces), limit_data and packet_loss. Each toxic applies to one direction, downstream (server to client, the default) or upstream, and a toxicity setting applies it to only a share of connections. A test wraps a block of code in a toxic, asserts that the app degrades the way it should (say, showing a post without tags when Redis is down) and removes the toxic afterwards.

Why teams pick it

  • Turns “what happens when Redis is slow?” into an ordinary, repeatable unit or integration test that runs in CI
  • Needs no root or kernel tools such as tc and iptables, and runs on Linux, macOS and Windows
  • Works with any TCP protocol, so one proxy setup covers databases, caches, queues and HTTP services
  • Adds almost nothing when idle: under 100 µs of latency with no toxics enabled

Watch out for

  • TCP only, and only between your app and dependencies you route through it: it can’t kill processes, stress CPU or break cloud resources
  • The app must be configured to connect through the proxy; MySQL clients that prefer the local Unix socket when the host is localhost bypass it
  • The HTTP API is unauthenticated unless you set TOXIPROXY_AUTH_TOKEN, and it can create proxies to any upstream, so it must never face an untrusted network
  • Made for test environments, not for running experiments against production traffic

Alternatives

What all chaos engineering have in common →Compare side by side →
Chaos MonkeyDormantOpen sourceNetflix’s original chaos tool: on weekdays it picks instances at random from each app managed by Spinnaker and terminates them, so teams build services that survive losing a machine.

How it fits with other technologies

Proxy Redis, then add a second of latency to every reply · bash

toxiproxy-server &

# the app's tests connect to localhost:26379 instead of 6379
toxiproxy-cli create -l localhost:26379 -u localhost:6379 redis

# every reply from Redis now takes 1 s (plus up to 500 ms of jitter)
toxiproxy-cli toxic add -t latency -a latency=1000 -a jitter=500 redis

# ...run the tests, then put things back
toxiproxy-cli toxic remove -n latency_downstream redis

See it in a real stack

No architecture uses Toxiproxy yet. Drop it into the playground and wire it up yourself.Open playground →
Where it came from2014–2026

Before Black Friday and Cyber Monday in 2014, Shopify’s infrastructure team made resiliency its top priority. They drew a matrix of which parts of the app broke when each external service was slow or down, and found that “minor dependencies” could become single points of failure. Simulating slow or dead services with tc and iptables needed sudo and didn’t fit automated tests, and no existing TCP proxy had an online API for changing proxies and deterministic latency.

So the team, writing up the work in a January 2015 post by Simon Eskildsen, built Toxiproxy and used it in all of Shopify’s development and test environments from October 2014, alongside Semian, its circuit breaker library. Version 1.0 came out in January 2015; 2.0 in April 2016 changed the API so that 1.x clients no longer worked. After a quiet spell between 2019 and 2021, releases resumed, and 2.13.0 came out in October 2026. Google Cloud’s chaos engineering recipes also use it, through a Chaos Toolkit extension, to cut the network between Cloud Run and Cloud SQL.

Why it’s built this way

A proxy with an HTTP API, not kernel tools
Tests need to switch faults on and off from code, quickly and without root, on developers’ laptops and in CI, which tc and iptables couldn’t offer.
Deterministic by default
A test must fail the same way every run to be useful, so toxics apply exactly as configured; randomness is opt-in through jitter and toxicity.
One shared proxy for many apps
Shopify recommends a single Toxiproxy with proxies named <app>_<env>_<data store>_<shard>, so several applications can use the same daemon without clashing.

Timeline

  1. 2014

    In use across Shopify’s development and test environments from October

  2. 2015

    Version 1.0 in January; Shopify describes it in “Building and Testing Resilient Ruby on Rails Applications”

  3. 2016

    Toxiproxy 2.0 changes the API

  4. 2021

    Releases resume with 2.1.5 after a gap since 2019

  5. 2026

    Toxiproxy 2.13.0 in October

Sources5 · facts checked 24 October 2026

Improve this page on GitHub