Skip to content
Get packs

Toxiproxy

A TCP proxy that lets tests inject network failures like latency and dropped connections.

GitHub Download v2.13.0
Stars
12.5k
Forks
519
Licence
MIT
Language
Go
Last update
10 days ago
Type
Dev tool

What it is

Toxiproxy sits between your application and the services it talks to, such as databases or caches. Your tests route connections through it, and then you can add delays, cut connections, or limit bandwidth through a simple HTTP API. It is meant for testing, CI, and development environments, so you can check whether your application handles failures gracefully.

  • Use the latency toxic to add a fixed delay to MySQL responses during a test run
  • Take down all Redis instances inside a block of test code to confirm the app returns a fallback value
  • Use the bandwidth, slicer, or packet_loss toxics to simulate poor network conditions

Great for

  • Engineers writing integration or unit tests that need to simulate a database or cache going down
  • Teams who want to check how their app behaves under added latency or slow connections
  • Developers who need a cross-platform alternative to Linux tools like nc that require root

Not ideal for

  • Production traffic management, since the README positions it for testing, CI, and development environments
  • Projects that do not use TCP connections between services
  • Users who want a ready-made client library in a language not listed in the README without writing or adapting one
Step-by-step guide: how to use ToxiproxyInstall, first run, examples, tips and FAQs

How to get it

  1. 1

    Install with a package manager

    Install with Homebrew (macOS)

    brew tap shopify/shopify && brew install toxiproxy

    Pull the Docker image

    docker pull ghcr.io/shopify/toxiproxy
  2. 2

    Run it

    • Install Toxiproxy using a package manager, a release binary, or Docker
    • Start the toxiproxy server, which listens for the HTTP API
    • Populate proxies that map a listen address to an upstream service, using a client library or the CLI
    • Point your application's test connections at the proxy's listen address
    • Add toxics to a proxy during a test to simulate failure conditions
  3. 3

    Get the most out of it

    • Use the populate endpoints or a client library to define proxies in test setup code
    • Use TOXIPROXY_AUTH_TOKEN when the API is reachable from other machines, as the README advises for Docker host networking
    • Check the Metrics and Logging sections of the README for observability options
    • Combine toxics such as latency with down to test specific failure scenarios

Downloads

Source code (.zip)main branch · straight from GitHubRelease v2.13.08 files incl. toxiproxy-server-linux-arm64Official website & docsgithub.com/shopify/toxiproxy

Strengths

  • Configurable through an HTTP API, so tests can change network conditions at runtime
  • Works without root access and runs on Linux, macOS, and Windows according to the release binaries
  • Has been used in Shopify's development and test environments since October 2014, per the README

Trade-offs

  • Client libraries are separate projects, and the README examples are in Ruby, so non-Ruby users must check client availability
  • Version 2.x is not compatible with 1.x, so existing setups may need client upgrades
  • The README is truncated, so details on some features and configuration are not visible here

How it compares

ProjectStarsTypeLevelUpdatedBest for
toxiproxy (this)12.5kDev toolintermediate10 days agoEngineers writing integration or unit tests that need to simulate a database or cache going down
storybook91.4kDev toolintermediate4 days agoFrontend teams building a shared component library or design system
mitmproxy46.6kDev toolintermediate4 days agoDevelopers debugging how an app talks to a backend API
promptfoo26.7kDev toolintermediate4 days agoDevelopers building apps on top of LLM APIs who want repeatable prompt tests
opencodex18.2kDev toolintermediate4 days agoDevelopers who already use Codex or Claude Code and want to try other model providers
whistle15.8kDev toolintermediate9 days agoFront-end developers who want to redirect or modify requests and responses without changing server code

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.