Chaos Internet Simulator

Break your network before your users do.

Chaos Internet Simulator is an open source local proxy + dashboard + CLI to simulate real-world bad internet and unstable APIs during development.

Why this project?

Most teams test with perfect localhost network. Production is not perfect.

Chaos Internet Simulator helps teams reproduce realistic failure modes early, before users see them.

Who is this for?

• frontend developers validating loading/error states
• backend developers testing retries and idempotency
• QA and SRE teams stress-testing app resilience
• DX and platform teams creating reproducible failure drills

Examples of what you can test

• slow navigation and high latency
• random API 5xx errors
• intermittent timeouts
• unstable HTTPS tunnels (CONNECT drops/timeouts)
• selective chaos by URL/path/domain
• scenario-based progressive degradation

Dashboard Preview

Monorepo structure

chaos-Internet-simulator/
├── apps/
│   ├── proxy/
│   ├── dashboard/
│   └── cli/
├── packages/
│   ├── core/
│   └── presets/
├── docs/
├── examples/
├── plugins/
├── recordings/
└── ...

Installation

pnpm install

Quick demo

pnpm dev
curl -x http://localhost:8080 https://jsonplaceholder.typicode.com/posts/1

Local usage

cp .env.example .env
pnpm dev

Open:

• Dashboard: http://localhost:3000
• Proxy: http://localhost:8080
• Control API: http://localhost:8081

Docker usage

docker compose up --build

Prebuilt release images (GHCR):

• ghcr.io/florextech/chaos-internet-simulator-proxy:latest
• ghcr.io/florextech/chaos-internet-simulator-dashboard:latest

Publish automation:

• GitHub Action: .github/workflows/publish-docker.yml
• Runs on release publish and workflow_dispatch

CLI usage

pnpm --filter @florexlabs/chaos-net build
pnpm --filter @florexlabs/chaos-net exec chaos-net status
pnpm --filter @florexlabs/chaos-net exec chaos-net start
pnpm --filter @florexlabs/chaos-net exec chaos-net profile unstable-api
pnpm --filter @florexlabs/chaos-net exec chaos-net logs
pnpm --filter @florexlabs/chaos-net exec chaos-net scenario bad-mobile-network
pnpm --filter @florexlabs/chaos-net exec chaos-net record start
pnpm --filter @florexlabs/chaos-net exec chaos-net record stop
pnpm --filter @florexlabs/chaos-net exec chaos-net replay sample.json
pnpm --filter @florexlabs/chaos-net exec chaos-net replay off

Without cloning this repo:

npm i -g @florexlabs/chaos-net
chaos-net status

cURL usage

curl -x http://localhost:8080 https://jsonplaceholder.typicode.com/posts
bash examples/curl_examples.sh

Postman usage

Import:

• examples/postman_collection.json

Then configure proxy host localhost port 8080.

Axios / fetch usage

• Axios sample: examples/node-axios-example.ts
• fetch (undici) sample: examples/node-fetch-example.ts
• Full workflow guide: docs/developer-workflows.md

HTTP_PROXY and HTTPS_PROXY

export HTTP_PROXY=http://localhost:8080
export HTTPS_PROXY=http://localhost:8080

chaos.config.json

Supported fields:

• enabled
• activeProfile
• targetBaseUrl
• proxyPort
• controlApiPort
• rules
• customProfiles

Example:

{
  "enabled": true,
  "activeProfile": "slow-3g",
  "targetBaseUrl": "https://jsonplaceholder.typicode.com",
  "proxyPort": 8080,
  "controlApiPort": 8081,
  "rules": [{ "match": "/posts", "profile": "slow-3g" }],
  "customProfiles": {
    "my-bad-network": {
      "delayMs": 3500,
      "errorRatePercent": 10,
      "timeoutRatePercent": 5,
      "timeoutMs": 12000
    }
  }
}

Priority:

1. env vars
2. chaos.config.json
3. defaults

Available profiles

• normal
• slow-3g
• airport-wifi
• unstable-api
• total-chaos
• starbucks-wifi
• colombia-4g
• office-vpn
• international-latency
• road-trip-network

Scenarios

• bad-mobile-network (loop)
• api-degrading

HTTPS support and limitations

• HTTPS traffic is supported through CONNECT tunneling.
• Chaos can apply delay, timeout, forced error, and connection drop before tunnel establishment.
• MITM is intentionally not implemented in this phase.
• Encrypted HTTPS payload is not inspected or rewritten.

Dashboard

Dashboard provides:

• chaos on/off and active profile controls
• target URL and per-route rule editor
• custom profile editor
• real-time logs
• metrics overview cards
• Playwright E2E tests for key flows (render, toggle, config updates)

UI Library (@florexlabs/ui)

Dashboard now uses @florexlabs/ui as the reusable UI base.

Use it in any project without cloning:

pnpm add @florexlabs/ui

import '@florexlabs/ui/florex.css';
import { Button, Card, Input } from '@florexlabs/ui';

Migrated components:

• Button
• Card
• Badge
• Input
• Container
• Section
• Spinner
• EmptyState

Still local (by design):

• native select controls in profile/rules forms (simple keyboard-native behavior)
• request log table structure and density styles (proxy-specific data layout)

Basic usage example:

import { Badge, Button, Card, Input } from '@florexlabs/ui';

Metrics

GET /metrics exposes:

• totalRequests
• delayedRequests
• erroredRequests
• timedOutRequests
• throttledRequests
• droppedConnections
• averageResponseTimeMs
• activeProfile
• activeScenario
• chaosEnabled

Plugins

• Local plugins loaded from plugins/
• Hooks: onRequest, onResponse
• Capabilities: forceError, addDelay, skipChaos, setHeader, dropConnection
• Plugin failures are isolated and logged

See:

• docs/plugins.md
• plugins/random-auth-failure.example.ts

Record & Replay

Control API:

• POST /record/start
• POST /record/stop
• POST /replay/start
• POST /replay/stop

Recordings are JSON files under recordings/.

Control API

• GET /health
• GET /state
• POST /state/enabled
• POST /state/profile
• POST /state/rules
• POST /state/target-base-url
• GET /logs
• GET /metrics
• GET /profiles
• POST /profiles/custom
• GET /scenario
• GET /scenarios
• POST /scenario
• POST /scenario/off
• POST /record/start
• POST /record/stop
• POST /replay/start
• POST /replay/stop

Detailed docs

• docs/README.md
• docs/proxy.md
• docs/dashboard.md
• docs/cli.md
• docs/configuration.md
• docs/developer-workflows.md
• docs/plugins.md
• docs/ui-system.md

Scripts

• pnpm dev
• pnpm build
• pnpm test
• pnpm lint
• pnpm format

Roadmap

Already done:

• HTTPS basic support via CONNECT tunneling (without MITM)
• temporal scenarios support (API, CLI, dashboard visibility)
• local plugin system with request/response hooks
• record and replay mode with JSON storage

Still pending:

• optional MITM HTTPS mode
• richer scenario editor in dashboard
• plugin marketplace ideas
• HAR import/export helpers

Contributing

See CONTRIBUTING.md.

License

MIT (LICENSE)