Minimal-dependency L4/L7 load balancer for any backend. One binary. Written in pure Go. Only stdlib + golang.org/x/{crypto,net,text} — no external frameworks. Works with Node.js, Python, Java, Go, Rust, .NET, PHP — anything that speaks HTTP or TCP.
-orange){kind=icon}
curl -sSL https://openloadbalancer.dev/install.sh | shCreate olb.yaml (or run olb setup for an interactive wizard):
admin:
address: "127.0.0.1:8081"
listeners:
- name: http
address: ":80"
routes:
- path: /
pool: web
pools:
- name: web
algorithm: round_robin
backends:
- address: "10.0.1.10:8080"
- address: "10.0.1.11:8080"
health_check:
type: http
path: /health
interval: 10solb start --config olb.yamlThat's it. HTTP proxy on :80, admin API on :8081, health checks every 10s, round-robin across two backends.
# Linux / macOS
curl -sSL https://openloadbalancer.dev/install.sh | sh
# Windows (PowerShell)
irm https://openloadbalancer.dev/install.ps1 | iex
# Docker (GHCR)
docker pull ghcr.io/openloadbalancer/olb:latest
docker run -d -p 80:80 -p 8081:8081 \
-v ./olb.yaml:/etc/olb/configs/olb.yaml \
ghcr.io/openloadbalancer/olb:latest
# Homebrew
brew tap openloadbalancer/olb && brew install olb
# Build from source
git clone https://github.com/openloadbalancer/olb.git && cd olb && make buildRequires Go 1.26+. Only stdlib + golang.org/x/{crypto,net,text}.
Proxy: HTTP/HTTPS, WebSocket, gRPC, SSE, TCP (L4), UDP (L4), SNI routing, PROXY protocol v1/v2, Request Shadowing/Mirroring
Load Balancing: 16 algorithms — Round Robin, Weighted RR, Least Connections, Weighted Least Connections, Least Response Time, Weighted Least Response Time, IP Hash, Consistent Hash (Ketama), Maglev, Ring Hash, Power of Two, Random, Weighted Random, Rendezvous Hash, Peak EWMA, Sticky Sessions
Geo-DNS Routing (experimental): a GeoIP rule engine (country, region, city) is included and its geodns config is parsed, but it does not affect routing yet.
Security: TLS termination + SNI, ACME/Let's Encrypt, mTLS, OCSP stapling, 6-layer WAF (IP ACL, rate limiting, request sanitizer, detection engine with SQLi/XSS/path traversal/CMDi/XXE/SSRF, bot detection with JA3 fingerprinting, response protection with security headers + data masking), circuit breaker
Middleware: 30 config-gated components plus always-on recovery and access log — trace, real IP, request logging, force SSL, metrics, request ID, IP filter, bot detection, max body size, cache, WAF (6-layer pipeline), rewrite, strip prefix, validator, request coalescing, JWT, HMAC, API key, basic auth, CSRF, timeout, rate limit, circuit breaker, CORS, CSP, headers, compression (gzip), transformer, retry, secure headers. An enabled middleware with an invalid config stops the engine from starting instead of being skipped.
Observability: Web UI dashboard (8 pages), TUI (olb top), Prometheus metrics, structured JSON logging, admin REST API (15+ endpoints), Grafana dashboard
Operations: Hot config reload (SIGHUP or API), Raft clustering, MCP server for AI integration, plugin system, 30+ CLI commands, request shadowing/mirroring
Not wired yet (experimental libraries): SWIM gossip membership, service discovery providers (Static/DNS/Consul/Docker/File) and the distributed rate limiter exist under internal/ with tests, but the engine does not use them and they have no config. Backends are listed statically under pools[].backends.
OpenLoadBalancer includes a built-in Model Context Protocol (MCP) server that enables AI agents (Claude, GPT, Copilot) to monitor, diagnose, and manage the load balancer.
- SSE (Server-Sent Events):
GET /ssefor streaming +POST /messagefor commands — MCP spec compliant - HTTP POST:
POST /mcpfor simple request/response (backwards compatible) - Stdio: Line-delimited JSON-RPC over stdin/stdout for local CLI tools
admin:
mcp_address: ":8082"
mcp_token: "your-secret-token" # Bearer token auth
mcp_audit: true # Log all tool calls8 core tools, plus 9 WAF tools when the WAF is enabled.
| Category | Tools |
|---|---|
| Metrics | olb_query_metrics — RPS, latency, error rates, connections |
| Backends | olb_list_backends, olb_modify_backend — Add, remove, drain, enable/disable |
| Routes | olb_modify_route — Add, update, remove routes with traffic splitting |
| Diagnostics | olb_diagnose — Automated error/latency/capacity/health analysis |
| Config | olb_get_config, olb_get_logs, olb_cluster_status |
| WAF | waf_status, waf_add_whitelist, waf_add_blacklist, waf_remove_whitelist, waf_remove_blacklist, waf_list_rules, waf_get_stats, waf_get_top_blocked_ips, waf_get_attack_timeline |
{
"mcpServers": {
"olb": {
"url": "http://localhost:8082/sse",
"headers": {
"Authorization": "Bearer your-secret-token"
}
}
}
}Benchmarked on AMD Ryzen 9 9950X3D:
| Metric | Result |
|---|---|
| Peak RPS | 15,480 (10 concurrent, round_robin) |
| Proxy overhead | 137µs (direct: 87µs → proxied: 223µs) |
| RoundRobin.Next | 3.5 ns/op, 0 allocs |
| Middleware overhead | < 3% (full stack vs none) |
| WAF overhead (6-layer) | ~35μs per request, < 3% at proxy scale |
| Binary size | ~13 MB |
| P99 latency (50 conc.) | 22ms |
| Success rate | 100% across all tests |
Algorithm comparison (1000 req, 50 concurrent)
| Algorithm | RPS | Avg Latency | Distribution |
|---|---|---|---|
| random | 12,913 | 3.5ms | 32/34/34% |
| maglev | 11,597 | 3.8ms | 68/2/30% |
| ip_hash | 11,062 | 4.0ms | 75/12/13% |
| power_of_two | 10,708 | 4.0ms | 34/33/33% |
| least_connections | 10,119 | 4.4ms | 33/33/34% |
| consistent_hash | 8,897 | 4.6ms | 0/0/100% |
| weighted_rr | 8,042 | 5.6ms | 33/33/34% |
| round_robin | 7,320 | 6.3ms | 35/33/32% |
Full benchmark report
See docs/benchmark-report.md for the complete report including concurrency scaling, backend latency impact, and middleware overhead measurements.
56+ end-to-end tests across 70 packages with 95.3% coverage:
| Category | Verified |
|---|---|
| Proxy | HTTP, HTTPS/TLS, WebSocket, SSE, TCP, UDP |
| Algorithms | RR, WRR, LC, IPHash, CH, Maglev, P2C, Random, RingHash |
| Middleware | Rate limit (429), CORS, gzip (98% reduction), WAF 6-layer (SQLi/XSS/CMDi/path traversal → 403, rate limit → 429, monitor mode, security headers, bot detection, IP ACL, data masking), IP filter, circuit breaker, cache (HIT/MISS), headers, retry |
| Operations | Health check (down/recovery), config reload, weighted distribution, session affinity, graceful failover (0 downtime) |
| Infra | Admin API, Web UI, Prometheus, MCP server, multiple listeners |
| Performance | 15K RPS, 137µs proxy overhead, 100% success rate |
| Algorithm | Config Name | Use Case |
|---|---|---|
| Round Robin | round_robin |
Default, equal backends |
| Weighted Round Robin | weighted_round_robin |
Unequal backend capacity |
| Least Connections | least_connections |
Long-lived connections |
| Least Response Time | least_response_time |
Latency-sensitive |
| IP Hash | ip_hash |
Session affinity by IP |
| Consistent Hash | consistent_hash |
Cache locality |
| Maglev | maglev |
Google-style hashing |
| Ring Hash | ring_hash |
Consistent with vnodes |
| Power of Two | power_of_two |
Balanced random |
| Random | random |
Simple, no state |
Supports YAML, JSON, TOML, and HCL with ${ENV_VAR} substitution.
admin:
address: "127.0.0.1:8081"
middleware:
rate_limit:
enabled: true
requests_per_second: 1000
cors:
enabled: true
allowed_origins: ["*"]
compression:
enabled: true
waf:
enabled: true
mode: enforce
detection:
enabled: true
threshold: {block: 50, log: 25}
bot_detection: {enabled: true, mode: monitor}
response:
security_headers: {enabled: true}
listeners:
- name: http
address: ":8080"
routes:
- path: /api
pool: api-pool
- path: /
pool: web-pool
pools:
- name: web-pool
algorithm: round_robin
backends:
- address: "10.0.1.10:8080"
- address: "10.0.1.11:8080"
health_check:
type: http
path: /health
interval: 5s
- name: api-pool
algorithm: least_connections
backends:
- address: "10.0.2.10:8080"
weight: 3
- address: "10.0.2.11:8080"
weight: 2See docs/configuration.md for all options.
The geodns section is parsed and validated, but GeoDNS rules do not influence routing yet. Use separate listeners/routes per region until it is wired in.
shadow:
enabled: true
percentage: 10.0 # Mirror 10% of traffic
copy_headers: true
copy_body: false
timeout: 30s
targets:
- pool: staging-pool
percentage: 100.0waf:
enabled: true
rate_limit:
enabled: true
store:
type: redis
address: "localhost:6379"
database: 0
rules:
- id: per-ip
scope: ip
limit: 1000
window: 1molb setup # Interactive config wizard
olb start --config olb.yaml # Start proxy
olb stop # Graceful shutdown
olb reload # Hot-reload config
olb status # Server status
olb top # Live TUI dashboard
olb backend list # List backends
olb backend drain web-pool 10.0.1.10:8080
olb health show # Health check status
olb config validate olb.yaml # Validate config
olb cluster status # Cluster info ┌─────────────────────────────────────────────────┐
│ OpenLoadBalancer │
Clients ─────────┤ │
HTTP/S, WS, │ Listeners → Middleware → Router → Balancer → Backends
gRPC, TCP, UDP │ (L4/L7) (30 types) (trie) (16 algos) │
│ │
│ WAF (6 layers) │ TLS │ Cluster │ MCP │ Web UI │
│ Shadow │ Prometheus │ Plugins │ ACME │
└─────────────────────────────────────────────────┘
See CONTRIBUTING.md. Key rules:
- Minimal external deps — stdlib + golang.org/x/{crypto,net,text} only
- Tests required — 85% coverage, don't lower it
- All features wired — no dead code in engine.go
- gofmt + go vet — CI enforced
Apache 2.0 — LICENSE