mroki

README

Safe shadow traffic testing for production systems.

mroki mirrors live HTTP traffic to a shadow service, diffs the JSON responses, and surfaces the differences — so you can validate changes against real production behavior before rolling out.

See the full screenshot gallery for more views.

Quick Start

# Start the dev stack (PostgreSQL + API + Proxy)
docker compose -f build/dev/compose.yaml up -d

# Create a gate (live/shadow service pair)
curl -s -X POST http://localhost:8090/gates \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mroki-dev-api-key-16" \
  -d '{"live_url": "https://httpbin.org/anything?env=live", "shadow_url": "https://httpbin.org/anything?env=shadow"}'

# Send traffic through the proxy
curl http://localhost:8080/get

Responses from both services are compared automatically. Open mroki-hub to browse gates, requests, and diffs.

See the Getting Started guide for the full walkthrough.

How It Works

A gate is a pair of services: a live (production) URL and a shadow (experimental) URL.

A proxy forwards each request to both services and sends the raw responses to the API — without affecting the live response. The API computes the JSON diff server-side.

The hub is a web UI for managing gates, browsing captured requests, and visualizing response diffs side-by-side.

Architecture

graph TD
    Client([Client]) -->|HTTP Request| Proxy[mroki-proxy]
    Proxy -->|Forward| Live[Live Service]
    Proxy -->|Forward| Shadow[Shadow Service]
    Live -->|Live Response| Proxy
    Shadow -->|Shadow Response| Proxy
    Proxy -->|Return live response| Client
    Proxy -.->|Send raw responses| API[mroki-api<br><i>REST API + Diff</i>]
    API -->|Store| DB[(PostgreSQL)]
    Hub[mroki-hub<br><i>Web UI</i>] -->|Query| API

Use Cases

API refactoring — Test refactored endpoints against real production traffic to catch behavioral regressions before they ship.

Database migrations — Run your new schema in shadow mode and verify it returns identical results to the current one.

Framework upgrades — Upgrade your framework on the shadow service and validate with real request patterns, not synthetic tests.

Documentation

	Guide	Description
🚀	Getting Started
	Full Stack	All-in-one Docker Compose — proxy, API, hub, database
	Standalone Proxy	Single binary, diffs to stdout, no database
	Caddy Module	Embedded in an existing Caddy server
🏗️	Production
	Docker Compose	Production deployment with Compose
	Kubernetes	K8s manifests and Helm charts
	Configuration	All environment variables and options
	Security	Auth, TLS, redaction, hardening
	Monitoring	Logging, health checks, observability
🔌	API
	Walkthrough	Step-by-step: create a gate, capture traffic, query diffs
	Reference	Full endpoint specification
📖	Reference
	Architecture	System design, data flow, technology choices
	Diff Pipeline	How responses are compared and diffed
	Troubleshooting	Common issues and fixes
	Roadmap	What's planned

Development

make dev-up   # Start dev stack
make test     # Run all tests
make build    # Build all binaries
make lint     # Lint

See the Development Guide for the full workflow.

Contributing

Contributions welcome. Please read the Contributing Guide before submitting PRs.

This project follows the Contributor Covenant Code of Conduct.

License

MIT