Chaos Proxy

Chaos Proxy is a proxy server for injecting configurable network chaos (latency, failures, connection drops, rate-limiting, and transforms) into HTTP traffic.

Use it via CLI or programmatically with ordered middleware chains (global and per-route).

Features

• YAML-based config with runtime reload support
• Built-in middleware primitives for latency, errors, drops, limits, throttling, and transforms
• Route matching by method and path
• Optional OpenTelemetry tracing export
• Extensible middleware registry

Installation

npm install chaos-proxy

Quick Start

CLI

npx chaos-proxy --config chaos.yaml [--verbose]

Programmatic API

import { loadConfig, startServer } from 'chaos-proxy';

const cfg = loadConfig('chaos.yaml'); // port comes from chaos.yaml
const server = await startServer(cfg);

// ...run your traffic through http://localhost:5000 (or whatever port is set in chaos.yaml)

await server.close();

Minimal Config

target: "http://localhost:4000"
port: 5000
global:
  - latency: 100

Documentation

Detailed guides live in docs/index.md:

• Chaos middlewares
• Observability
• Hot reload
• Examples

Presets

Ready-made chaos bundles are available in presets:

• mobile-3g.yaml
• flaky-backend.yaml
• burst-errors.yaml
• timeout-storm.yaml

Runtime Reload

Chaos Proxy supports runtime config reload via POST /reload. See docs/hot-reload.md for full details.

Join the Community

Have questions, want to discuss features, or share examples? Join the Fetch-Kit Discord server:

License

MIT