PatchPanel

A state-driven web UI for HAProxy. Render haproxy.cfg from a validated JSON document, validate it with haproxy -c, reload via the master CLI socket, and manage TLS certificates (Let’s Encrypt + BYO) — all from a browser.

Get started API reference GitHub

---

What it does

PatchPanel turns HAProxy from a hand-edited haproxy.cfg into a state-driven, declarative system:

• State-driven rendering — A single state.json is the source of truth. Every save re-renders haproxy.cfg, runs haproxy -c against it, and atomically swaps the file. Bad config never reaches a running worker.
• Zero-downtime reloads — Master CLI socket reloads (-W -S). Old workers drain gracefully.
• Let’s Encrypt baked in — DNS-01 (Cloudflare, Route 53, Google, DigitalOcean, OVH, RFC 2136, dns-multi) and HTTP-01. Multiple ACME accounts. Bring-your-own PEM uploads for hosts you renew elsewhere.
• Trusted CAs and CRLs — Upload root + intermediate bundles and revocation lists; reference them on bind lines for mTLS and on server lines for upstream verification.
• Live observability — Per-frontend/backend traffic, stats socket runtime API, audit log, snapshot timeline, GeoIP origin map.
• Authentication — Local admin login (session cookies) + bcrypt-hashed API keys (Bearer tokens) for programmatic / remote control.
• Two deployment surfaces — Home Assistant add-on, standalone Debian package (.deb from the STARTcloud apt repository).

Getting started

Home Assistant add-on

1. Add https://github.com/STARTcloud/homeassistant-addons to your HA add-on repositories.
2. Install the HAProxy add-on.
3. Start it. The first run seeds an empty state document at /data/state.json.
4. Open the HAProxy sidebar item in Home Assistant.
5. Run through the setup wizard to add your first ACME account, route, and backend.

Standalone Debian

# Add the STARTcloud apt repository (one-time)
curl -fsSL https://packages.debian.startcloud.com/startcloud.gpg \
  | sudo tee /etc/apt/keyrings/startcloud.gpg > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/startcloud.gpg] https://packages.debian.startcloud.com bookworm main" \
  | sudo tee /etc/apt/sources.list.d/startcloud.list

sudo apt update
sudo apt install patchpanel haproxy

# First run prints a setup token to the terminal
sudo journalctl -fu patchpanel

Open https://your-host:8099/, paste the setup token, create the first admin account, and finish the configuration wizard.

Concepts

• State document — Zod-validated JSON. Frontends, backends, ACLs, rules, certs, providers, trusted CAs / CRLs, ACME accounts. Every change is a write to /data/state.json (HA addon) or /var/lib/patchpanel/state.json (standalone), which triggers a render + validate + atomic-swap + reload.
• Renderer — Deterministically renders haproxy.cfg from the state document plus a small bootstrap config (paths, ports, SSL).
• Audit log — SQLite-backed log of every state change, attributed to the editor (local user, API key, or HA user when running as add-on).

Documentation

• Architecture — Components, data flow, process model
• API reference — OpenAPI spec + interactive Swagger UI
• Releases — Download .deb / view release notes
• Changelog — Per-version change log

About

PatchPanel is © 2026 STARTcloud.

License

GPL-3.0. See LICENSE.

Contributing

Discuss the change you want to make via issue first. CONTRIBUTING.

Thank you to the contributors

• 
• 
• 

Code of Conduct

Contributor Covenant 2.1.