Architecture Overview

Diverge is a Kubernetes-native engine that uses a single consolidated Docker image containing multiple binaries.

Components

1. Controller: The brain of Diverge. A standard Kubernetes operator that watches the Environment, PreviewGroup, and AgentTask CRDs. It manages the lifecycle of preview environments, directly creates Argo CD Application CRs via Server-Side Apply, handles database provisioning and autonomous sandboxes, and ensures clean finalizer-based teardowns.
2. Proxy: A lightweight layer-7 router that intercepts traffic, inspects RFC 7230 compliant headers, and dynamically routes requests to either the preview namespace or the shared baseline.
3. Activator Proxy: A specialized reverse proxy that sits in front of scaled-to-zero preview environments. It tracks ready pods via a shared informer, routes to active pods directly, and falls back to the Knative activator to wake up dormant environments on-demand.
4. Webhook Handler: An HTTP server that securely processes incoming GitHub and GitLab webhooks, executing strict payload validation before triggering the controller.
5. Server: An optional ConnectRPC API server that provides a stateless CRD facade (Environment, PreviewGroup, AgentTask), embedded React Web Dashboard, remote /mcp server, and live POST /api/v1/agenttask/meter budget governance over HTTPS (:8443) and in-cluster HTTP (:8080).
6. Agent Runner (cmd/agent-runner): The reference autonomous agent sandbox entrypoint (ghcr.io/divergedev/agent-runner) that authenticates via Macaroon capability tokens, clones DIVERGE_REPO_URL, runs a metered build-verify-fix loop against the linked preview environment, and pushes verified fixes.
7. CLI: A developer tool (diverge) for creating, validating, verifying, and managing preview environments and AgentTask sandboxes locally or in CI.
8. Status Reporter: Posts commit status checks (diverge/preview) to GitLab and GitHub for merge gating. Validates commit SHAs against a hex-only regex to prevent path traversal.

Security Architecture Highlights

Diverge is built with a Security First mindset:

• Attenuated Macaroon Capability Tokens & Sandbox NetworkPolicies: Autonomous AgentTask sandboxes authenticate with HMAC-SHA256 chained Macaroons (task_id, namespace, repo, branch, tools, models, max_cost_usd, max_tokens, expires, nonce) and, in the release namespace and namespaces listed in sandbox.networkPolicy.targetNamespaces, are isolated by diverge-sandbox-isolation NetworkPolicy rules blocking cloud metadata (169.254.169.254/32), private RFC1918 ranges, and direct Kubernetes API access.
• RBAC-Scoped Client: The controller operates with the minimum required permissions necessary to manage specific namespaces and resources.
• Constant-Time Secret Comparison: Webhook secrets are validated securely to prevent timing attacks.
• Path Traversal Prevention: Input validation guards against directory traversal in GitHub/GitLab webhook handling.
• Shell/Markdown Injection Prevention: All templates and outputs are sanitized to prevent injection attacks.
• Strict YAML Unmarshaling: Configuration parsing uses DisallowUnknownFields to prevent misconfigurations or tampering.
• Context Timeouts: All external network calls enforce strict context timeouts.
• SHA Validation: Commit SHAs are validated against a hex-only regex before use in API URLs.
• Label Validation: Namespace label keys/values are validated using Kubernetes validation utilities.
• SQL Injection Prevention: Schema names use regex-gated validation since parameterized DDL isn’t possible.

Async Routing Architecture

To handle non-HTTP workloads, Diverge creates dedicated infrastructure (e.g., Kafka topics) per preview environment. Configuration is injected into the pods, ensuring strict isolation of asynchronous message flows.

SDK Context Propagation

Diverge SDKs propagate the necessary routing context (like headers) through background threads and inter-service calls, ensuring the entire request lifecycle remains within the intended environment.

Server Metrics Collection

The Diverge Server exposes a rich set of Prometheus metrics (e.g., diverge_server_rpc_requests_total) and health endpoints, allowing operators to monitor system performance and set up alerting.

Flow Diagram

graph TD
    Dev[Developer] -->|Push Code| Git[GitHub / GitLab]
    Git -->|Webhook Event| Webhook[Diverge Webhook Handler]
    Webhook -->|Create/Update| CRD[Environment CRD]
    
    CRD --> Controller[Diverge Controller]
    
    Controller -->|Server-Side Apply| Argo[Argo CD]
    Controller -->|Commit Status| Git
    Controller -->|Provision| DB[(Database)]
    
    Argo -->|Deploy| PreviewNs[Preview Namespace]
    
    User[User / CI] -->|HTTP Request + Header| Proxy[Diverge Proxy]
    
    Proxy -->|Header Match| PreviewNs
    Proxy -->|No Match| BaselineNs[Baseline Namespace]