Home

Breeze Core

Self-hosted control for Midea air conditioners: a LAN-first REST API, a web control panel, a diagnostic CLI, and an optional native Android app. After a one-time local pairing there is no cloud dependency — commands go from your browser or phone to your own server to the unit, over your own network.

This wiki is the full documentation. The repository README is the short version.

---

Pick your starting point

If you…	Go to
run Linux and want updates through your package manager	Installing from packages
already run containers	Installing with containers
run Windows	Installing on Windows
run OPNsense	Installing on OPNsense
run macOS, a BSD, Alpine, NixOS, or anything unusual	Installing from source
have it installed and want to pair your units	First run and pairing
are writing a client, or automating it	REST API · Control schema
want to reach it from outside the house	Exposing it safely — read this first
have something broken	Troubleshooting

---

What it is

Four decoupled components sharing exactly one contract, the /api/* endpoints. Delete any client and the rest keeps working.

Component	What it is
Server	A FastAPI app — the only stateful part, and a standalone REST API that neither knows nor cares that a UI exists.
Web panel	Self-contained vanilla-JS ES modules served by the app. Just an HTTP client.
CLIs	A diagnostic battery and an approval tool, both HTTP-only. See Command-line tools.
Breeze for Android	Optional native app: one unit per screen, home-screen widgets, Android Auto, programs, diagnostics. Its own repo ↗

Built on msmart-ng for device I/O, FastAPI + uvicorn for HTTP, and plain ES modules for the panel — no build step anywhere. Architecture, layer by layer: Architecture.

What you get out of the box

• Control from anywhere on your LAN — browser, Android app, home-screen widgets, Android Auto, REST, curl, cron.
• Automation that runs on the server — favourites, schedules and temperature curves fire whether or not your phone is home, charged, or awake. See Programs, schedules, curves.
• Live state without polling — Server-Sent Events push every change, whether it came from you, a schedule, or another client.
• Two-credential access with Ed25519 request signing, LAN-gated admin approval, per-device revocation. See Authentication and pairing.
• Real diagnostics — breeze-core diag --auto checks auth posture, per-unit latency, capability probing and input validation, and the same battery is mirrored in the app.
• Packages, not tarballs — deb, rpm, pacman, apk, OpenWrt ipk, FreeBSD, NetBSD, an OPNsense plugin, a Windows installer, five container images, and a signed repository so updates arrive the normal way.
• Quiet by default — the beep is off unless a client asks for it, so a 3 a.m. setpoint change wakes nobody.

No account, no telemetry, no cloud callbacks after pairing, no "pro" tier. It is AGPL-3.0.

What it is not

Worth knowing before you invest an evening — the longer version, with the full trade-off table, is in Compared to NetHome Plus.

• It needs a machine that is always on, and you are now its sysadmin.
• Pairing is not fully local. Units join Wi-Fi through the vendor app, and V3 units need one internet-connected discovery run to fetch their token and key. Everything after that is offline — back those credentials up.
• Nothing is exposed to the internet by default. Control from away means a VPN (recommended) or a proxy you secure yourself.
• The feature ceiling is your firmware's. No filter reset, no energy dashboard, and some units silently ignore horizontal swing.
• The native app is Android-only. iOS and desktop get the web panel.
• It is not a home-automation platform. One brand, one job. If you already run Home Assistant, its Midea integration may suit you better.