A security-first reverse proxy built to guard the free web.
Sleepable ops at the edge.
Documentation • Playground • Benchmarks • Discussions • Contributing
Zentinel is a high-performance reverse proxy built on Cloudflare Pingora. It provides explicit limits, predictable behavior, and production-grade defaults for environments where operators need to sleep.
Performance: Lowest p99 latency in benchmarks against Envoy, HAProxy, Nginx, and Caddy. 1M-request soak tests with 99.95% success rate and zero memory leaks. Pure Rust WAF engine processes clean traffic at 912K req/s — 30x faster than the C++ ModSecurity reference.
Production-ready core (proxy, routing, TLS, caching, load balancing). Agents are individually versioned — WAF, Auth, and AI Gateway are stable; others are beta or alpha. See zentinelproxy.io/agents for per-agent status.
# Install
curl -fsSL https://getzentinelproxy.io | sh
# Or via Cargo
cargo install zentinel-proxy
# Or via Docker
docker run -v $(pwd)/zentinel.kdl:/etc/zentinel/zentinel.kdl \
ghcr.io/zentinelproxy/zentinel --config /etc/zentinel/zentinel.kdlSave this as zentinel.kdl — it proxies localhost:8080 to a backend on port 8081:
system {
worker-threads 0 // auto-detect CPU cores
}
listeners {
listener "http" {
address "0.0.0.0:8080"
protocol "http"
}
}
routes {
route "default" {
matches {
path-prefix "/"
}
upstream "backend"
}
}
upstreams {
upstream "backend" {
target "127.0.0.1:8081"
}
}# Run
zentinel --config zentinel.kdl
# Validate config without starting
zentinel test --config zentinel.kdlMore examples: config/examples/ covers API gateways, load balancing, WebSocket, caching, inference routing, and more. Or use the config builder to generate a config interactively.
| Feature | Description |
|---|---|
| Service Types | Web, API, Static, Builtin, and Inference (LLM/AI) |
| Load Balancing | 14 algorithms: round-robin, weighted, least connections, Maglev, Peak EWMA, and more |
| Security | TLS/mTLS, rate limiting, GeoIP filtering, WAF, zip bomb protection |
| Agent Protocol | External agents for WAF, auth, and custom logic — crash-isolated, any language |
| HTTP Caching | Pingora-based response caching with stampede prevention and S3-FIFO + TinyLFU eviction |
| WebSocket Proxying | RFC 6455 compliant with frame inspection and traffic mirroring |
| Observability | Prometheus metrics, structured logging, OpenTelemetry tracing |
| Hot Reload | Zero-downtime config updates via SIGHUP with validation and atomic swap |
See the full feature breakdown at zentinelproxy.io/features.
- Reverse Proxy — TLS termination, static file serving, compression, and security headers for web applications
- API Gateway — Versioned routing, JWT/API key auth, per-client rate limiting, and JSON error responses
- Load Balancer — Weighted traffic distribution, health checks, circuit breakers, and blue-green/canary deployments
- Inference Gateway — Token-based rate limiting, model routing with glob patterns (
gpt-4*,claude-*), prompt injection detection, and PII filtering for OpenAI, Anthropic, and generic LLM providers - WebSocket Gateway — Persistent connection proxying with frame inspection, message rate limiting, and session affinity
- Security Gateway — WAF, GeoIP filtering, mTLS, and composable agent pipelines for custom security logic
Example configs for each: config/examples/
Modern proxies accumulate hidden behavior, unbounded complexity, and operational risk that surfaces under stress. Zentinel takes a different approach:
- Bounded resources — Memory limits, queue depths, deterministic timeouts. No surprise behavior.
- Explicit failure modes — Fail-open or fail-closed per route, never ambiguous.
- External extensibility — Security logic lives in agents, not the core. Small, stable dataplane.
- Observable by default — Every decision is logged and metered. Features ship only when bounded, observed, and tested.
The goal is infrastructure that is correct, calm, and trustworthy. See MANIFESTO.md for the full philosophy.
Zentinel's security and extensibility lives in agents — external processes that hook into every request phase. Agents are crash-isolated from the proxy, independently deployable, and can be written in any language.
Agent SDKs: Rust · Go · Python · TypeScript · Elixir · Kotlin · Haskell
| Agent | Description |
|---|---|
| WAF | Pure Rust WAF — 200+ detection rules, ML-powered anomaly scoring, zero C dependencies |
| AI Gateway | Prompt injection detection, jailbreak prevention, PII filtering for LLM APIs |
| Policy | Multi-engine policy evaluation (Rego/OPA and Cedar) — written in Haskell |
| Auth | JWT, OIDC, SAML, mTLS, API keys with Cedar-based fine-grained authorization |
| Chaos | Latency injection, error simulation, connection resets with safety guardrails |
| Lua | Sandboxed Lua scripting with VM pooling, hot-reload, and resource limits |
| ZentinelSec | Pure Rust ModSecurity — OWASP CRS-compatible SecLang parser, zero C dependencies |
| WebSocket Inspector | Content filtering, JSON/MessagePack validation, and rate limiting for WebSocket frames |
| MQTT Gateway | IoT protocol security with topic ACLs, auth, and payload inspection |
Browse all 25+ agents at zentinelproxy.io/agents.
Crates
Each crate has its own docs/ directory with detailed documentation.
| Crate | Description |
|---|---|
zentinel-proxy |
Core reverse proxy built on Pingora |
zentinel-config |
KDL configuration parsing and validation |
zentinel-agent-protocol |
Agent protocol v1 (legacy) and v2 (current) |
zentinel-common |
Shared types, errors, and utilities |
wasm-runtime |
WASM agent runtime using Wasmtime |
playground-wasm |
Browser bindings for the config playground |
sim |
WASM-compatible configuration simulator |
stack |
All-in-one process manager for proxy and agents |
zentinel-control-plane — Fleet management for Zentinel proxies, built with Elixir/Phoenix. Centralized configuration, rolling deploys, and real-time observability across your Zentinel instances.
See CONTRIBUTING.md for guidelines.
Using Claude Code? See .claude/CLAUDE.md for project context, architecture, and coding rules.
- 📖 Documentation — Guides, reference, and examples
- 🎮 Playground — Try the routing engine in your browser (WASM)
- 📊 Benchmarks — Performance, soak testing, and Envoy comparison
- 💬 Discussions — Questions, ideas, show & tell
- 🐛 Issues — Bug reports and feature requests
Apache 2.0 — See LICENSE.
