pughost

pughost

Localhost is a lie. Test in reality.

Your API works flawlessly on localhost. Then it hits production—users on 3G in Lagos, satellite connections in rural areas, congested airport WiFi—and everything breaks. Timeouts, race conditions, spinners that never stop.

Pughost injects real-world network chaos into your local development. Find the bugs before your users do.

What It Does

Pughost is a network simulation layer between your local client and server. It introduces:

• Latency — delayed responses (3G, satellite)
• Jitter — variable delays (unstable connections)
• Bandwidth limits — throttled data transfer
• Packet loss — dropped connections

Installation

npm install -g pughost

Automatically downloads the correct binary for your OS (macOS, Linux, Windows) and architecture (x64, arm64). No manual setup required.

Quick Start

1. Initialize — Generate a config file in your project:

pughost init

This creates pughost.json:

{
  "upstream": "localhost:3000",
  "proxyPort": 3001,
  "scenarios": {
    "mobile_3g_slow": { "latency": 1000, "jitter": 500, "bandwidth": 50 },
    "wifi_cafe_crowded": { "latency": 100, "jitter": 800, "packet_loss": 0.05 },
    "satellite_link": { "latency": 800, "bandwidth": 1000 }
  }
}

2. Start your backend — Run your server on its normal port (e.g., 3000).

3. Activate chaos — Start the proxy with a scenario:

pughost start -s mobile_3g_slow

4. Test through the proxy — Point your client to http://localhost:3001 instead of :3000.

Endpoint	Behavior
localhost:3000	Normal (dev mode)
localhost:3001	Chaos (reality mode)

Commands

Command	Description
pughost init	Create pughost.json config file
pughost list	Show available scenarios
pughost start -s <name>	Start proxy with scenario
pughost --help	Show all commands

Scenario Parameters

Parameter	Unit	Description
latency	ms	Base delay added to responses
jitter	ms	Random variance in latency
bandwidth	kbps	Max data transfer rate
packet_loss	0.0–1.0	Probability of connection drop

Use Cases

• Mobile app testing — Simulate 3G/4G conditions against your local API
• Emerging markets — Test for users in Nigeria, India, Indonesia
• Resilience testing — Verify timeout handling, retry logic, loading states
• QA workflows — Consistent network conditions for bug reproduction

How It Works

Pughost wraps Toxiproxy (by Shopify) and manages its lifecycle automatically. You get battle-tested chaos engineering without the setup complexity.

Requirements

• Node.js >= 18
• Internet access on first install (downloads Toxiproxy binary)

License

MIT © Victor Durosaro