zentinelproxy · raffaelschneider · Jul 1, 2026 · Jul 1, 2026
diff --git a/config.toml b/config.toml
@@ -55,9 +55,10 @@ logo = "img/zentinel-mascot.png"
 
 # Version picker
 [extra.versions]
-current = "26.06"
+current = "26.07"
 list = [
-    { version = "26.06", url = "/", label = "latest" },
+    { version = "26.07", url = "/", label = "latest" },
+    { version = "26.06", url = "/v/26.06/", label = "" },
     { version = "26.05", url = "/v/26.05/", label = "" },
     { version = "26.04", url = "/v/26.04/", label = "" },
     { version = "26.02", url = "/v/26.02/", label = "" },

diff --git a/content/v/26.07/_index.md b/content/v/26.07/_index.md
@@ -0,0 +1,158 @@
++++
+title = "Introduction"
+weight = 0
+sort_by = "weight"
+template = "section.html"
++++
+Welcome to **Zentinel**, a high-performance **reverse proxy** platform built on [Cloudflare's Pingora](https://github.com/cloudflare/pingora) framework. Zentinel extends Pingora's robust foundation with enterprise-grade features designed for modern web infrastructure.
+
+## What is Zentinel?
+
+Zentinel is a next-generation reverse proxy that combines the performance and reliability of Pingora with advanced routing capabilities, service-type awareness, and comprehensive error handling. Whether you're serving static files, proxying REST APIs, or managing complex web applications, Zentinel provides the tools and flexibility you need for production deployments.
+
+## Key Features
+
+### High Performance
+- Built on Pingora's async Rust foundation
+- Memory-safe architecture with zero-copy operations
+- Efficient connection pooling and keep-alive management
+- Optimized for both throughput and latency
+
+### Service-Type Awareness
+Zentinel understands different service types and optimizes behavior accordingly:
+
+- **Web Applications**: HTML error pages, session handling, SPA support
+- **REST APIs**: JSON schema validation, structured error responses, OpenAPI integration
+- **Static Files**: Direct file serving, automatic MIME types, caching headers
+
+### Advanced Routing
+- Flexible path-based and host-based routing
+- Route priorities and groups
+- Path variables and pattern matching
+- Per-route configuration overrides
+
+### Comprehensive Error Handling
+- Service-type-specific error formats (HTML, JSON, XML, Text)
+- Custom error page templates with variable substitution
+- Graceful fallbacks for connection failures
+- Detailed error tracking with request IDs
+
+### Observability
+- Structured logging with configurable levels
+- Prometheus-compatible metrics
+- Distributed tracing support
+- Health check endpoints
+
+### Security Features
+- Path traversal protection for static files
+- Request validation and sanitization
+- Rate limiting capabilities
+- TLS/SSL with modern cipher suites
+- HTTP/3 preparation with QUIC support (ready for activation)
+
+### Configuration
+- Human-friendly KDL configuration format
+- Hot reload without downtime
+- Environment variable substitution
+- Comprehensive validation on startup
+
+## Why Zentinel?
+
+### Production-Ready
+Zentinel is designed for production use from the ground up. Every feature is implemented with reliability, performance, and operational excellence in mind.
+
+### Type-Safe and Memory-Safe
+Written in Rust, Zentinel eliminates entire classes of bugs common in traditional proxies, including buffer overflows, use-after-free errors, and data races.
+
+### Cloud-Native
+Built for modern cloud environments with support for:
+- Container deployments (Docker, Kubernetes)
+- Horizontal scaling
+- Service mesh integration
+- Dynamic configuration
+
+### Developer-Friendly
+- Clear, expressive configuration
+- Comprehensive error messages
+- Extensive documentation
+- Example configurations for common use cases
+
+## Use Cases
+
+Zentinel excels in various deployment scenarios:
+
+- **API Gateway**: Validate requests, transform responses, implement rate limiting
+- **Static Content Delivery**: Serve files directly with optimal caching headers
+- **Load Balancer**: Distribute traffic across multiple upstream servers
+- **Web Application Proxy**: Handle sessions, provide custom error pages, support SPAs
+- **Microservices Router**: Route requests to different services based on paths
+- **Edge Proxy**: Terminate SSL, implement security policies, cache responses
+
+## Architecture Highlights
+
+Zentinel leverages Pingora's battle-tested architecture while adding its own innovations:
+
+```text
+Client Request
+     ↓
+[TLS Termination]
+     ↓
+[Route Matching] ← Service Type Detection
+     ↓
+[Request Processing]
+     ├─→ Static File Serving (no upstream)
+     ├─→ API Validation → Upstream
+     └─→ Web App Processing → Upstream
+     ↓
+[Response Processing]
+     ├─→ Error Page Generation
+     ├─→ Header Manipulation
+     └─→ Caching Headers
+     ↓
+Client Response
+```
+
+## Getting Started
+
+This documentation will guide you through:
+
+1. **[Installation](./getting-started/installation.md)** — Get Zentinel up and running
+2. **[Quick Start](./getting-started/quick-start.md)** — Your first proxy configuration
+3. **[Core Concepts](./concepts/architecture.md)** — Understand how Zentinel works
+4. **[Configuration](./configuration/file-format.md)** — Master the configuration system
+5. **[Features](./features/)** — Explore all capabilities
+6. **[Deployment](./deployment/docker.md)** — Deploy to production
+
+## Documentation Structure
+
+- **[Getting Started](./getting-started/)** — Installation and basic setup
+- **[Core Concepts](./concepts/)** — Fundamental architecture and design principles
+- **[Configuration](./configuration/)** — Detailed configuration reference
+- **[Features](./features/)** — Complete feature list with code references
+- **[Agents](./agents/)** — External agent system for extensibility
+- **[Operations](./operations/)** — Production management and troubleshooting
+- **[Deployment](./deployment/)** — Container and cloud deployment guides
+- **[Control Plane](./control-plane/)** — Fleet management, rollouts, and observability
+- **[Examples](./examples/)** — Real-world configuration examples
+- **[Reference](./reference/)** — Metrics, CLI, and API documentation
+- **[Development](./development/)** — Contributing to Zentinel
+
+## Community
+
+- 💬 **[Discussions](https://github.com/zentinelproxy/zentinel/discussions)** — Questions, ideas, show & tell
+- 🐛 **[Issues](https://github.com/zentinelproxy/zentinel/issues)** — Bug reports and feature requests
+- 📦 **[GitHub](https://github.com/zentinelproxy/zentinel)** — Source code and releases
+
+Contributions are welcome! See our [Contributing Guide](./development/contributing.md) to get started.
+
+## Version Information
+
+This documentation covers Zentinel release **26.04**. For the latest updates and changes, see the [Changelog](./appendix/changelog.md). For details on the versioning scheme, see [Versioning](./appendix/versioning.md).
+
+## License
+
+Zentinel is open-source software licensed under the Apache License, Version 2.0. See the [License](./appendix/license.md) page for details.
+
+---
+
+Ready to get started? Head to the [Installation Guide](./getting-started/installation.md) to begin your journey with Zentinel!
diff --git a/content/v/26.07/agents/_index.md b/content/v/26.07/agents/_index.md
@@ -0,0 +1,158 @@
++++
+title = "Agents"
+weight = 8
+sort_by = "weight"
+template = "section.html"
++++
+
+Agents are the primary extension mechanism for Zentinel. They allow you to add custom logic, security policies, and integrations without modifying the core proxy.
+
+## Protocol
+
+Zentinel uses the **v2 agent protocol** for all agent communication:
+
+| Feature | Details |
+|---------|---------|
+| **Transports** | UDS (binary), gRPC, Reverse Connections |
+| **Connection Pooling** | Multiple connections per agent with load balancing (4 strategies) |
+| **Streaming** | Full bidirectional streaming support |
+| **Observability** | Built-in metrics export in Prometheus format |
+| **Config Push** | Dynamic configuration updates |
+| **Health Tracking** | Comprehensive health checks |
+| **Flow Control** | Backpressure support |
+| **Request Cancellation** | Cancel in-flight requests when clients disconnect |
+
+See the [v2 protocol documentation](v2/) for full details.
+
+---
+
+## What Are Agents?
+
+Agents are **external processes** that communicate with Zentinel over a well-defined protocol. When a request flows through Zentinel, configured agents receive events at key lifecycle points and can:
+
+- **Inspect** request/response headers and bodies
+- **Modify** headers, routing metadata, and more
+- **Decide** to allow, block, redirect, or challenge requests
+- **Log** audit information for observability
+
+```
+┌───────────────────────────────────────────────────────────────────────────┐
+│                             Zentinel Proxy                                 │
+│  ┌─────────────────────────────────────────────────────────────────────┐  │
+│  │                          Agent Manager                               │  │
+│  │  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐        │  │
+│  │  │   Auth    │  │ RateLimit │  │    WAF    │  │  Policy   │        │  │
+│  │  │  Client   │  │  Client   │  │  Client   │  │  Client   │        │  │
+│  │  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘        │  │
+│  └────────┼──────────────┼──────────────┼──────────────┼──────────────┘  │
+└───────────┼──────────────┼──────────────┼──────────────┼─────────────────┘
+            │              │              │              │
+            ▼              ▼              ▼              ▼
+     ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
+     │ Auth Agent │ │ RateLimit  │ │ WAF Agent  │ │  Policy    │
+     │  (local)   │ │   Agent    │ │  (remote)  │ │  Agent     │
+     └────────────┘ └────────────┘ └────────────┘ └────────────┘
+          UDS           gRPC           gRPC         Reverse
+```
+
+## Why External Agents?
+
+Zentinel's architecture keeps the dataplane minimal and predictable:
+
+| Benefit | Description |
+|---------|-------------|
+| **Isolation** | A buggy or crashing agent cannot take down the proxy |
+| **Independent Deployment** | Update agents without restarting Zentinel |
+| **Language Flexibility** | Write agents in any language with gRPC or Unix socket support |
+| **Circuit Breakers** | Zentinel protects itself from slow or failing agents |
+| **Horizontal Scaling** | Run agents as separate services for high availability |
+
+## Transport Options
+
+Agents can communicate with Zentinel via multiple transports:
+
+| Transport | Protocol | Best For |
+|-----------|----------|----------|
+| **Unix Socket** | Binary + JSON | Local agents, lowest latency |
+| **gRPC** | Protocol Buffers over HTTP/2 | High throughput, streaming, remote |
+| **Reverse Connection** | Binary | NAT traversal, dynamic scaling |
+
+## Quick Configuration Example
+
+```kdl
+agents {
+    // Unix socket agent with pooling
+    agent "auth-agent" type="auth" {
+        unix-socket "/var/run/zentinel/auth.sock"
+        connections 4
+        events "request_headers"
+        timeout-ms 100
+        failure-mode "closed"
+    }
+
+    // gRPC agent
+    agent "waf-agent" type="waf" {
+        grpc "http://localhost:50051"
+        connections 4
+        events "request_headers" "request_body"
+        timeout-ms 200
+        failure-mode "open"
+        circuit-breaker {
+            failure-threshold 5
+            timeout-seconds 30
+        }
+    }
+}
+
+// Reverse connection listener
+reverse-listener {
+    path "/var/run/zentinel/agents.sock"
+    max-connections-per-agent 4
+    handshake-timeout "10s"
+}
+
+routes {
+    route "api" {
+        matches { path-prefix "/api/" }
+        upstream "backend"
+        agents "auth-agent" "waf-agent"
+    }
+}
+```
+
+## Building Your Own Agent
+
+The easiest way to build a custom agent is with the **Zentinel Agent SDK**:
+
+```rust
+use zentinel_agent_protocol::v2::{AgentPool, AgentPoolConfig};
+
+let pool = AgentPool::new();
+pool.add_agent("my-agent", "/var/run/my-agent.sock").await?;
+
+let response = pool.send_request_headers("my-agent", &headers).await?;
+```
+
+The SDK provides ergonomic wrappers around the protocol, handling connection management, health tracking, and metrics automatically.
+
+## Documentation
+
+| Page | Description |
+|------|-------------|
+| [WAF Engines](waf-engines/) | Choosing between WAF, ZentinelSec, and ModSecurity agents |
+
+### Protocol Reference
+
+| Page | Description |
+|------|-------------|
+| [Protocol Specification](v2/protocol/) | Wire protocol, message types, streaming |
+| [API Reference](v2/api/) | AgentPool, client, and server APIs |
+| [Connection Pooling](v2/pooling/) | Load balancing and circuit breakers |
+| [Transport Options](v2/transports/) | gRPC, UDS, and Reverse comparison |
+| [Reverse Connections](v2/reverse-connections/) | NAT traversal setup |
+
+### Legacy (Removed)
+
+| Page | Description |
+|------|-------------|
+| [Protocol v1](v1/) | Historical v1 documentation (removed in 26.02_18) |
diff --git a/content/v/26.07/agents/v1/_index.md b/content/v/26.07/agents/v1/_index.md
@@ -0,0 +1,22 @@
++++
+title = "Protocol v1 (Removed)"
+weight = 20
+sort_by = "weight"
++++
+
+{% callout(type="warning", title="V1 Protocol Removed") %}
+Agent Protocol v1 was **removed** in Zentinel release 26.02_18 (February 2026). All agents must use [Protocol v2](../v2/). The documentation below is preserved for historical reference only.
+{% end %}
+
+## Documentation (Historical)
+
+| Page | Description |
+|------|-------------|
+| [Protocol Specification](protocol/) | Wire protocol and message formats |
+| [Events & Hooks](events/) | Request lifecycle events agents can handle |
+| [Building Agents](building/) | How to create your own agent |
+| [Transport Protocols](transports/) | Unix sockets and gRPC connectivity |
+
+## Migrating to v2
+
+All agents must use [Protocol v2](../v2/). See the [v2 documentation](../v2/) for the current protocol specification, API reference, and transport options.