Deterministic fixed-target chaos proxy for TCP streams and UDP datagrams. Place it between a client and its dependency to inject latency, bandwidth limits, blackholes, byte limits, slow closes, slicing, disconnects, or stream loss. Fault decisions are reproducible from versioned seeds. upstream means client to target; downstream means target to client.
TCP faults shape userspace byte streams. UDP faults apply to whole datagrams. Eggchaos is not a forward proxy, TLS interceptor, or IP-layer impairment tool.
The current release is v0.2.1. Install with Rust 1.89 or newer:
cargo install eggchaos-cli --version 0.2.1 --lockedPrebuilt CLI binaries are available from the v0.2.1 GitHub release. To run from a source checkout:
cargo run -p eggchaos-cli -- serve --config eggchaos.tomlThis example adds 200 ms latency with 50 ms of jitter to replies. It uses a small local echo server as the target. To test a real dependency instead, set upstream to its address and skip step 1.
1. Start the target in a terminal:
python3 -c '
import socket
s = socket.socket()
s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
s.bind(("127.0.0.1", 19999))
s.listen(8)
while True:
c, _ = s.accept()
c.sendall(c.recv(4096))
c.close()
' &2. Save this configuration as eggchaos.toml:
version = 1
seed = 7
[admin]
bind = "127.0.0.1:8475"
[[proxy]]
name = "backend"
listen = "127.0.0.1:16379"
upstream = "127.0.0.1:19999"
[[proxy.fault]]
id = "lag"
direction = "downstream"
type = "latency"
delay = "200ms"
jitter = "50ms"3. Start Eggchaos and leave it running:
eggchaos serve --config eggchaos.tomlUse another terminal for the remaining commands. Check that the service is ready:
eggchaos health
curl -s http://127.0.0.1:8475/v1/proxies4. Send traffic to the proxy listener at 127.0.0.1:16379:
python3 - <<'PY'
import socket
import time
with socket.create_connection(("127.0.0.1", 16379), timeout=5) as s:
start = time.perf_counter()
s.sendall(b"ping")
reply = s.recv(100).decode()
elapsed_ms = round((time.perf_counter() - start) * 1000)
print(reply, elapsed_ms, "ms")
PYExpect roughly 150 to 250 ms, plus local scheduling overhead. The configured jitter varies the 200 ms base delay by up to 50 ms in either direction.
No restart is needed. When a stream policy changes, preserving bytes accepted under the old generation drain before the new generation takes effect.
eggchaos fault list backend
eggchaos fault set backend lag --kind latency --delay-ms 400 --jitter-ms 50
eggchaos fault remove backend lag
eggchaos fault add backend lag --direction downstream --kind latency --delay-ms 200
eggchaos connection list
eggchaos history
eggchaos resetRe-run the traffic command after each change. fault set needs --probability and/or --kind. Supplying --kind rebuilds that fault from the attributes provided, so repeat any values you want to keep. Omitted attributes use their defaults.
Fault probability defaults to 1.0. Stream fault activation is deterministic per connection; datagram fault probability is evaluated per datagram. Both use seeded, fault-local decisions rather than process-global randomness.
TCP stream faults are latency, bandwidth, blackhole, limit-data, slow-close, slice, disconnect, and stream-loss. UDP datagram faults are delay, loss, duplicate, reorder, payload-corrupt, and bandwidth.
See configuration for TOML fields, control plane for API and CLI schemas, and architecture for fault behavior.
- UDP proxy: configure
[[datagram_proxies]]or use theeggchaos datagramCLI commands. See datagram configuration. - Toxiproxy compatibility: run the loopback compatibility server with
cargo run -p eggchaos-toxiproxy --example compat_server -- 127.0.0.1:8474. See Toxiproxy compatibility. - Eggfetch integration:
eggchaos-eggfetchapplies policies to physical connections while Eggfetch retains HTTP, TLS, and pooling responsibilities. See Eggfetch integration. - Embedding and scenarios:
eggchaos-embedruns the service in-process, andeggchaos-experimentprovides Scenario V2 schedules. See control plane. - Remote SDKs: source-only Python and TypeScript clients control the native API. They do not manage the daemon lifecycle. See control plane.
| Document | Covers |
|---|---|
| Architecture | Crate boundaries and fault semantics |
| Configuration | TOML schema, defaults, and runtime bounds |
| Control plane | Admin API, CLI, scenarios, metrics, and SDKs |
| Toxiproxy | Compatibility profiles and differences |
| Eggfetch | In-process transport integration |
The native admin listener is unauthenticated on loopback by default; treat that as a same-user trust boundary. Non-loopback access requires public_admin = true and a bearer token with at least 32 non-whitespace bytes. Requests are checked against the bind-derived Host set or exact [admin].allowed_hosts; mutations also validate any present Origin, and non-empty bodies require JSON media type. The listener is cleartext HTTP, so protect remote access with a trusted TLS terminator and network controls. The CLI's --admin-token value may appear in local process listings; prefer EGGCHAOS_ADMIN_TOKEN or a protected secret mechanism and avoid shell history. The Toxiproxy compatibility API is unauthenticated and loopback-only unless the caller explicitly opts into public binding; that opt-in does not add TLS or authentication. See admin configuration, control-plane security, and Toxiproxy exposure.
Repository governance uses active main and release-tag rulesets: main requires pull requests, current required checks, linear history, and resolved review threads, with a sole-maintainer bypass limited to pull requests; release tags are restricted to the release owner. Secret scanning, push protection, Dependabot alerts, and Dependabot security updates are enabled. Non-provider pattern scanning and validity checks are not available on the organization’s current GitHub Free plan. The pinned CodeQL workflow has been added to the candidate but still requires an exact-head hosted run before its analysis is considered verified. See the security policy for current readbacks and limitations.
MIT. See LICENSE.