System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Kamal Proxy is a high-performance reverse proxy designed for zero-downtime deployments and resilient traffic management. Originally a fork of Basecamp's kamal-proxy, it provides enhanced features such as SAN certificate batching, wildcard certificates via DNS-01, and advanced traffic shaping (compression, rate limiting, and caching).
The system follows a layered architecture where a CLI interacts with a long-running server process over a Unix socket using Go's net/rpc. This allows for dynamic reconfiguration of services, load balancers, and TLS settings without restarting the proxy.
Sources: CLAUDE.md:3-9, CLAUDE.md:79-85, ROADMAP.md:4-8
Core Component Layers
The architecture is divided into four distinct layers that handle everything from entry-point execution to low-level socket management.
| Layer | Component | Description |
|---|---|---|
| Layer 3 | cmd/kamal-proxy | The main entry point and executable. |
| Layer 2 | internal/cmd | Cobra-based CLI that acts as an RPC client for commands like deploy and remove. |
| Layer 1 | internal/server | The core engine containing the Router, Service management, Load Balancer, and Cert Managers. |
| Layer 0 | Unix Socket / State | The communication channel (kamal-proxy.sock) and persistence (~/.config/kamal-proxy). |
Sources: CLAUDE.md:79-85, internal/cmd/deploy.go:170-174
System Component Diagram
The following diagram illustrates the relationship between the CLI, the RPC server, and the underlying request handling components.
Request Processing Workflow
When an HTTP/HTTPS request enters the proxy, it passes through a sophisticated middleware chain before reaching an upstream target.
Middleware Execution Logic
- Logging & Metrics: The request is first wrapped in logging and metrics tracking.
- IP Filtering: Deny lists and Allow lists (CIDR) are checked before any heavy processing.
- TLS/ACME Handling: If the request is an ACME HTTP-01 challenge, it is intercepted here.
- Redirection: TLS upgrades and canonical host redirects are processed.
- Security: Basic Auth and Rate Limiting are applied.
- Optimization: Response compression and caching logic are executed.
- Routing: The
Servicematches the request path and host to a specificLoadBalancer.
Sources: internal/server/service.go:720-745, internal/server/service.go:880-920, ROADMAP.md:44-55
Sequence Diagram: Request to Target Flow
This diagram shows the path of a request from the client through the proxy's internal logic.
Load Balancing and Deployment
The proxy manages zero-downtime deployments using two target slots: Active and Rollout.
Load Balancer Structure
The LoadBalancer manages a TargetList, which distinguishes between Write targets (primary application instances) and Read targets (replicas). It handles health checks and optionally enforces session affinity.
- Target Slots: Used to transition traffic between versions.
- Writer Affinity: Keeps clients on the same target for a duration after a write request (e.g., POST/PUT).
- Health Checks: Performed at configurable intervals (
DefaultHealthCheckInterval = 1s).
Sources: internal/server/service.go:50-65, internal/server/service.go:303-310, internal/server/load_balancer.go:210-230
Deployment Configuration
Deployment is triggered via the RPC Deploy method, which accepts DeployArgs containing both ServiceOptions and TargetOptions.
| Option | Type | Default | Description |
|---|---|---|---|
TargetURLs | []string | Required | Upstream target hosts with optional weights. |
DeployTimeout | Duration | 30s | Max time to wait for health checks to pass. |
DrainTimeout | Duration | 30s | Time to allow old connections to close. |
Weight | int | 1 | Traffic share (max 1000) for a specific target. |
Sources: internal/cmd/deploy.go:54-65, internal/server/service.go:76-80
TLS and Certificate Management
Kamal Proxy handles TLS through two main mechanisms: StaticCertManager (for manual certificates) and SANCertManager/autocert (for automated ACME).
Automated TLS Management
The proxy supports on-demand TLS where it can ask an external endpoint if a certificate should be issued for a specific domain. It also provides a unique feature for SAN certificate batching, reducing the number of individual certificate requests to ACME providers.
- State Persistence: All ACME state (account keys, certificates) is stored in a
certsdirectory within the data directory to survive restarts. - DNS-01 Support: Used for wildcard certificate provisioning.
Sources: CLAUDE.md:8-12, internal/server/service.go:785-805, ROADMAP.md:65-70
Summary
The Kamal Proxy architecture is built for operational stability. By separating the management plane (CLI/RPC) from the data plane (Router/LoadBalancer), and persisting all service configurations in state files, it ensures that traffic continues to flow correctly even across proxy version updates or container restarts. The integration of advanced features like writer affinity and session-aware load balancing makes it suitable for complex stateful applications.
Sources: CLAUDE.md:79-85, internal/server/service.go:273-294