Configuration examples organized by category.
cargo run -p praxis-proxy -- -c examples/configs/traffic-management/basic-reverse-proxy.yaml
curl http://localhost:8080/Configs use local ports (3000, 3001, ...) for
upstreams. For quick experiments without a real backend,
use static_response (see
static-response.yaml)
or run Praxis with no config file for a built-in welcome
page.
| File | Description |
|---|---|
| conditional-skip-to.yaml | Skips browser-facing middleware for clean requests |
| conditional-terminal.yaml | Short-circuits the pipeline when guardrails detects a dangerous request header |
| cross-chain-flat.yaml | A listener references two chains: preprocessing and routing |
| multiple-branches.yaml | Multiple branches on a single filter, evaluated in order |
| named-chain-ref.yaml | A branch references a top-level chain by name instead of defining filters inline |
| nested-branches.yaml | Branch filters that themselves contain branches, forming a multi-level decision tree |
| reentrance.yaml | Loops back to a named filter up to N times |
| unconditional-branch.yaml | Always runs a utility chain before continuing the main pipeline |
| File | Description |
|---|---|
| access-logging.yaml | Structured JSON logging with sampling; logs ~10% of requests. request_id ensures each log line has a correlation ID. access_log emits method, path, status, and timing |
| logging.yaml | request_id — ensures every request has a correlation ID |
| tcp-access-log.yaml | Structured JSON logging of TCP connection events (connect and disconnect) |
| File | Description |
|---|---|
| admin-interface.yaml | Exposes an admin endpoint for operational health checks, readiness probes, and Prometheus metrics |
| container-default.yaml | Default config for containerized deployments |
| hot-reload.yaml | Filter pipelines are swapped atomically at runtime when the config file changes |
| log-overrides.yaml | Use runtime.log_overrides to raise or lower log verbosity for specific modules without flooding output from every subsystem |
| max-connections.yaml | HTTP listeners return 503 with Retry-After: 1. TCP listeners close the socket immediately |
| multi-listener.yaml | Demonstrates multiple HTTP listeners, each with its own filter pipeline |
| production-gateway.yaml | Combines TLS, logging, timeouts, security headers, path routing, and load balancing |
| File | Description |
|---|---|
| body-size-limit-with-extraction.yaml | Combines body_limits.max_request_bytes with json_body_field to enforce a global body ceiling while still performing body-based routing |
| compression.yaml | Enables transparent response compression using Pingora's built-in compression module |
| conditional-field-extraction.yaml | Uses the condition system to apply json_body_field only on specific request paths |
| field-extraction-access-control.yaml | Extracts the "tenant_id" field from the JSON request body and promotes it to an X-Tenant-Id header |
| json-rpc.yaml | Extracts JSON-RPC 2.0 envelope metadata from request bodies and promotes method, id, and kind to request headers |
| multi-field-extraction.yaml | A single json_body_field filter extracts multiple top-level JSON fields into separate request headers in one pass |
| multi-listener-body-pipeline.yaml | Three listeners, each with a different body processing strategy |
| stream-buffer.yaml | json_body_field inspects request body chunks as they arrive and defers upstream forwarding until the field is extracted (or end-of-stream) |
| File | Description |
|---|---|
| default.yaml | Built-in default config (static JSON on /) |
| branch-chains.yaml | Filters write structured results to FilterResultSet |
| composed-chains.yaml | Multiple named chains are composed per listener |
| conditional-filters.yaml | Filters support conditions (request phase) and response_conditions (response phase) to gate execution |
| failure-mode.yaml | Demonstrates open and closed failure handling for filters |
| File | Description |
|---|---|
| mixed-protocol.yaml | HTTP and TCP listeners run on a single server instance |
| tcp-consistent-hash.yaml | TCP consistent-hash load balancing (client IP affinity) |
| tcp-least-connections.yaml | TCP least-connections load balancing |
| tcp-proxy.yaml | Bidirectional TCP forwarding |
| tcp-round-robin.yaml | TCP round-robin load balancing across database replicas |
| tcp-timeouts.yaml | TCP proxy with session and max duration timeouts. tcp_session_timeout_ms wraps the entire TCP forwarding session in a hard deadline, terminating connections after the threshold regardless of activity. tcp_max_duration_secs caps the total session duration in seconds |
| tcp-tls-mtls.yaml | The proxy requires TCP clients to present a valid TLS certificate signed by the trusted CA |
| tcp-tls-termination.yaml | TLS on the listener; plain TCP to the upstream backend |
| tls-cipher-suites.yaml | Restrict accepted cipher suites per listener |
| tls-http-reencrypt.yaml | HTTPS on the listener; TLS to the upstream backend |
| tls-mtls-both.yaml | Client mTLS to the proxy (client cert required), and proxy mTLS to the upstream backend (proxy presents its own client certificate) |
| tls-mtls-listener-request.yaml | The proxy requests a client certificate but does not require one |
| tls-mtls-listener.yaml | The proxy requires clients to present a valid TLS certificate signed by the trusted CA |
| tls-mtls-upstream.yaml | Plain HTTP from clients; the proxy presents a client certificate to the upstream backend, which requires mutual TLS authentication |
| tls-multi-cert.yaml | Multiple certificates on one listener; Praxis selects the certificate matching the client's SNI hostname |
| tls-sni-routing.yaml | Routes TLS connections to different upstreams based on the Server Name Indication (SNI) hostname in the ClientHello |
| tls-termination.yaml | HTTPS on the listener; plain HTTP to the backend |
| tls-verify-disabled.yaml | Plain HTTP listener; TLS to the upstream with certificate verification disabled |
| tls-version-constraint.yaml | Restrict accepted TLS versions via min_version |
| upstream-ca-file.yaml | Sets a trusted CA bundle for all upstream TLS connections via runtime.upstream_ca_file |
| upstream-tls.yaml | Plain HTTP on the listener; TLS to the upstream |
| websocket.yaml | HTTP listener that transparently proxies WebSocket upgrade requests |
| File | Description |
|---|---|
| cors.yaml | Spec-compliant CORS filter with preflight handling, origin validation, and credential support |
| credential-injection.yaml | Injects per-cluster API credentials into upstream requests |
| csrf.yaml | Cross-site request forgery protection via origin validation |
| downstream-read-timeout.yaml | Protects against slow client attacks by limiting how long the proxy waits for data from downstream clients |
| forwarded-headers.yaml | Injects X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host into upstream requests |
| guardrails.yaml | Reject requests that match header or body inspection rules |
| ip-acl.yaml | Allow or deny requests by source IP/CIDR |
| peer-identity-trust.yaml | Validates downstream mTLS peer identity against a set of trusted peers |
| policy-http.yaml | Generic-HTTP authorization for non-MCP traffic using the CPEX policy engine |
| policy.yaml | Embeds the CPEX policy engine in-process to enforce multi-source JWT identity, APL route policy, RFC 8693 OAuth 2.0 token exchange, PII scanning, audit emission, and (under body_access: read_write) request / response body rewriting |
| File | Description |
|---|---|
| basic-reverse-proxy.yaml | Minimal config: one listener, one upstream, default filter chain |
| canary-routing.yaml | Sends ~10% of traffic to a canary backend while the stable backend handles the remaining ~90% |
| circuit-breaker.yaml | Prevents cascading failures by tracking consecutive upstream errors per cluster |
| endpoint-selector.yaml | Selects an upstream endpoint from a trusted mutation source (e.g. ext_proc) |
| grpc-detection.yaml | Detects gRPC requests from the content-type header and promotes the variant to filter metadata and results |
| health-checks.yaml | Per-cluster health checks probe endpoints on a timer and remove unhealthy backends from the load balancer rotation |
| hostname-upstream.yaml | Demonstrates using DNS hostnames instead of IP addresses for upstream endpoints |
| hosts.yaml | One listener serves multiple domains |
| least-connections.yaml | Routes each request to the backend with the fewest in-flight requests |
| p2c.yaml | Samples two random endpoints and picks the one with fewer in-flight requests |
| path-based-routing.yaml | Routes by URL path prefix |
| rate-limiting.yaml | Token bucket rate limiter with per-IP or global modes |
| redirect.yaml | Returns a 3xx redirect without contacting any upstream |
| round-robin.yaml | Default strategy |
| session-affinity.yaml | Hashes a request header to pin a user's requests to one backend |
| static-response.yaml | Returns a fixed response without contacting any upstream |
| timeout.yaml | Returns 504 if the upstream takes longer than timeout_ms to respond |
| weighted-load-balancing.yaml | Traffic split proportional to per-endpoint weights |
| File | Description |
|---|---|
| header-manipulation.yaml | Add, overwrite, and remove headers on requests and responses |
| path-rewriting.yaml | Rewrite request paths before forwarding to upstream |
| url-rewriting.yaml | Regex-based path transformation and query string manipulation |