Umbrella. Alpha GitHub
Edge proxy · Open source · MIT

A customizable, fast,
open-source API
load balancer.

FastAPI inside. One Docker image. Five balancing strategies, active & passive health checks, atomic config reloads, ClickHouse-backed analytics, and a beautiful operator dashboard. No service mesh, no agents, no fuss.

View on GitHub → See live demo →
v0.1.0 · alpha FastAPI · Python 3.11+ SQLite default · Postgres opt-in ClickHouse analytics · optional
CLIENTS UMBRELLA BACKENDS client GET /api/... client GET /api/... client GET /api/... client GET /api/... // EDGE PROXY Umbrella. ROUND_ROBIN · 4/4 HEALTHY backend-01 10.0.1.10:8080 HEALTHY backend-02 10.0.1.11:8080 HEALTHY backend-03 10.0.1.12:8080 HEALTHY backend-04 10.0.1.13:8080 HEALTHY
5
Balancing strategies
<10ms
Proxy overhead p99
1
Docker container
0
Restarts on config change
Features

Built for operators
who want it small,
sharp, and visible.

Umbrella covers the load-balancing fundamentals you actually need — routing, health, observability — without dragging in a service mesh, a control plane, or a yaml mountain. Drop one container in front of your services and operate it from a single pane.

01 / Routing

Five balancing strategies

Round-robin, weighted, least-connection, IP-hash, and random. Switch live per pool — no restart, no dropped requests.

02 / Health

Active + passive health checks

Configurable probe interval, timeout, and expected status. A passive circuit breaker trips on consecutive 5xx and half-opens after a cool-off.

03 / Routing rules

Granular request matching

Match by path, host, method, headers, or query. Exact, prefix, glob, and regex patterns. Routes evaluated in priority order, first match wins.

04 / Config

Zero-restart reloads

Every write rebuilds an immutable in-memory snapshot atomically. The hot path reads from a single reference, so changes apply on the very next request.

05 / Analytics

SQL or ClickHouse, transparently

Per-minute traffic, p50/p95 latency, top routes, and top error paths. SQL by default; set UMBRELLA_CLICKHOUSE_URL to scale to billions of rows.

06 / Dashboard

Operator UI in the same binary

Manage pools, backends, routes, and users from one place. Live topology graph, JWT-cookie auth, first-run bootstrap. No separate frontend to deploy.

Quick start

One file.
Three minutes.

Clone the repo, run docker compose up. Coolify, Dokku, Fly, Railway, plain Docker on a VM — whatever runs containers runs Umbrella.

docker-compose.yml 
# umbrella in front, your apps behind. one process. one DB.
services:
  umbrella:
    build:
      context: .
      dockerfile: docker/Dockerfile
    restart: unless-stopped
    expose: ["8080"]
    environment:
      UMBRELLA_SECRET_KEY:     "${UMBRELLA_SECRET_KEY}"
      UMBRELLA_COOKIE_SECURE:  "true"
      UMBRELLA_DATABASE_URL:   "sqlite+aiosqlite:////app/data/umbrella.db"
      # optional: switch analytics to ClickHouse for production
      # UMBRELLA_CLICKHOUSE_URL: "http://default:pwd@clickhouse:8123/umbrella"
    volumes:
      - umbrella-data:/app/data

volumes:
  umbrella-data:
Full install guide → Read the docs →
Open source · MIT

Star it on GitHub.
Self-host in five minutes.

No SaaS. No telemetry. No upsell. The dashboard, the proxy, and the analytics live inside one Python package you can read in an evening.

Open the repo → See the dashboard →