Reverse Proxy

Supported reverse proxies

The cards only show the controls the proxy has.

Features

• Sensors for proxy rules, active rules, the inbound port, and per proxy: TLS certificates and access rules (Zoraxy), middlewares and version (Traefik), TLS certificates, access lists and version (Nginx Proxy Manager)
• One upstream health binary sensor per proxy rule (Zoraxy and Traefik: Nginx Proxy Manager does not check its upstreams)
• Repairs: an issue when a certificate expires within 30 days (an error once expired), and when every upstream of a rule has been offline for 10 minutes; each goes away by itself once fixed
• Zoraxy and Nginx Proxy Manager: one expiry sensor, one "expiring soon" binary sensor and one renewal button per certificate (a certificate added later in Zoraxy gets its entities at the next update); a reverse_proxy.toggle_proxy_rule action (administrators only) to enable or disable a proxy rule from an automation; Zoraxy: switches for the HTTPS redirect, the port 80 listener and the development mode
• A Lovelace card, shipped with the integration and registered automatically:
  • proxy status, brand mark and key metrics
  • proxy rules with the rule's state, a Down badge when the proxy finds the rule's upstream offline, and redirects
  • Zoraxy: direct controls (HTTPS redirect, port 80, dev mode; turning port 80 off asks for confirmation first, as it also stops the ACME HTTP challenges)
  • Zoraxy and Nginx Proxy Manager: certificates with days left and a renewal button, an on/off button per rule (disabling a rule asks for confirmation first)
  • an unavailable entity shows as Unavailable (its control disabled), never as Off or Inactive
• A mini card in the same file: status and key figures on two lines, alerts highlighted, and a detail button showing the full card; at its narrowest (4 columns of a Sections view) the status pill shows its coloured dot only
• Visual editors for both cards, light and dark mode, English, French, German, Spanish, Serbian (Cyrillic and Latin), Italian, Dutch, European Portuguese, Polish, Romanian, Danish, Swedish, Bulgarian, Russian, Ukrainian, Hungarian, Slovak, Czech, Slovenian, Latvian and Greek
• Several instances, of any of these proxies, each with its own device and card
• Automatic reconnection when the Zoraxy session (about one hour) or the Nginx Proxy Manager token (a day) expires

Prerequisites

• Home Assistant 2024.12 or later
• Zoraxy v3.3.2 or later and an account on its web interface, or Traefik with its API reachable from Home Assistant (api.insecure: true on the traefik entrypoint, or the dashboard router; with a basicAuth middleware, give the integration its credentials), or Nginx Proxy Manager v2 and an account on its admin interface (port 81) without two-factor authentication: a dedicated user whose permissions allow managing the proxy hosts and certificates is enough

Configuration

Integration#

Settings → Devices & services → Add integration → Reverse Proxy, pick Zoraxy, Traefik or Nginx Proxy Manager, then fill in:

The refresh interval and the TLS verification can be changed later with Configure on the integration. To change the address, the username (Nginx Proxy Manager: the email) or the password without removing the integration, use ⋮ → Reconfigure on it: the new settings are saved only once the proxy accepts them. When the proxy refuses the credentials, Home Assistant asks for new ones in Settings → Devices & services. Zoraxy entries created with version 1.5.0 or earlier keep the TLS verification off, as before; turn it on in the options if your certificate is valid.

Card#

Edit a dashboard, click Add card and search for Reverse Proxy Card. Set the proxy URL (opened when clicking the header icon) and, with several instances, the device. Or in YAML:

type: custom:reverse-proxy-card
proxy_url: http://zoraxy.local:8000

The card finds its entities in the entity registry, by their device and their kind, so renamed entity ids keep working, and reads which proxy the device is (and what its API allows) from the Proxy running binary sensor: a Traefik card has no controls, certificates or rule buttons, a Nginx Proxy Manager card no controls (its certificates and rule buttons are there). With several instances, pick the device of each card in the visual editor (or set device).

Mini card#

custom:reverse-proxy-mini-card shows the full card's essentials on two lines, for a compact dashboard: the header icon, title and status pill, then a chip per key figure:

• active / total proxy rules
• the number of rules whose upstream is down, in red, only when there are some
• Zoraxy and Nginx Proxy Manager: the number of certificates, or one chip per certificate expiring within 30 days (orange, red under 7 days), the closest first; Traefik: the number of middlewares
• the inbound port
• Zoraxy: HTTPS redirect Off and Dev mode On, in orange, only when they apply; Traefik and Nginx Proxy Manager: the version

Chips needing attention are tinted; a click on a chip opens its entity. The detail button (top right) switches the card to the full card, with the same configuration, and back, as does a click anywhere else on the page (zoom: false removes it). Search for Reverse Proxy Mini Card when adding a card, or in YAML:

type: custom:reverse-proxy-mini-card
proxy_url: http://zoraxy.local:8000
zoom: true

Same options as the full card, plus:

Entities#

Every proxy:

Zoraxy and Nginx Proxy Manager:

Zoraxy only:

Traefik only:

Traefik and Nginx Proxy Manager:

Names follow the Home Assistant language under the Zoraxy Reverse Proxy, Traefik Reverse Proxy or Nginx Proxy Manager device. Zoraxy entity ids keep their historical French suffixes (sensor.zoraxy_reverse_proxy_zoraxy_regles_proxy…) so dashboards and automations from 1.x keep working, on new installs too; Traefik and Nginx Proxy Manager entities get Home Assistant's default ids (sensor.traefik_reverse_proxy_proxy_rules, sensor.nginx_proxy_manager_proxy_rules…).

Repairs#

The integration raises issues in Settings → Repairs, removed by themselves once the cause is gone:

They follow the proxy's data: while the proxy itself can't be reached, the issues raised stay as they are. Removing the integration entry removes its issues.

Action reverse_proxy.toggle_proxy_rule (Zoraxy, Nginx Proxy Manager)#

The action is reserved to administrators. It fails (and the card's button goes back) when the rule is not found or the proxy refuses the change; for a Traefik rule it fails too, as Traefik's API is read-only. With several instances, the rule is looked up in all of them, unless config_entry_id names one.

action: reverse_proxy.toggle_proxy_rule
data:
  domain: myapp.example.com
  enable: false

How it works

The integration polls the proxy's API at the refresh interval. Zoraxy: it logs in to the web API and logs in again when the session expires; the uptime monitor's results (/api/utm/list) are read at most once a minute (Zoraxy itself checks each upstream every 5 minutes, every 30 seconds while it is down). Traefik: /api/overview, the HTTP routers, services, middlewares and entrypoints are read at each poll, the version once an hour. Nginx Proxy Manager: it asks for a token with the account's email and password (/api/tokens), then reads /api/, the proxy hosts, redirection hosts, certificates and access lists at each poll, and asks for a new token when it expires. The entities of a certificate or proxy rule added in the proxy appear at the next update, without reloading the integration, and those of a removed one are deleted.

On the card, the button next to each Zoraxy or Nginx Proxy Manager rule calls reverse_proxy.toggle_proxy_rule for the card's own instance; for users who are not administrators the button only shows the rule's state and is disabled, and a failed change shows its error in a toast; the button updates at once and the card refreshes when the integration has polled the proxy again. Certificates turn orange under 30 days and red under 7 days.

To debug:

logger:
  logs:
    custom_components.reverse_proxy: debug

⋮ → Download diagnostics on the integration gives its settings and the last data read from the proxy, with the address, usernames, passwords, tokens, secrets, cookies and email addresses replaced by **REDACTED**.

Support

If you find this project useful, you can support its development:

Fixes

• Nginx Proxy Manager: no more upstream health binary sensor per proxy host (#67). NPM does not check its upstreams, so these sensors (shown as Upstream {domain} / Serveur cible {domain}) could only ever be unknown, while the target of each proxy host is already in the Proxy rules sensor and on the card. Those created by 2.4.0 are removed at startup; Zoraxy and Traefik keep theirs.

Features

• Nginx Proxy Manager support (#65): add it with Settings → Devices & services → Add integration → Reverse Proxy → Nginx Proxy Manager (address of the admin interface, the email and password of an account without two-factor authentication). Its proxy hosts are the proxy rules (with their on/off button on the card and in reverse_proxy.toggle_proxy_rule), its redirection hosts the redirects; access lists, version, and the certificates with their expiry sensors and renewal button (Let's Encrypt certificates) are there too. NPM does not check its upstreams: their health stays unknown. The token is renewed by itself when it expires.

Features

• show_title and show_subtitle options (also in the visual editor) hide the header's title (the proxy's name) and its subtitle (its web address), separately, for a card placed under a section heading of its own (asked in juju35/ha-vehicle-card#72).

Maintenance

• No code change: released again to check the installation from the Marketplace.

Features

• Repairs issues: a certificate expiring within 30 days (warning) or expired (error), and a rule whose upstreams have all been offline for 10 minutes (error), in Settings → Repairs; each goes away by itself once fixed, and with the entry when it is removed.

Performance

• Translations load on demand: in the release zip, the frontend files keep English only (reverse-proxy-card.js 108 KB → 76 KB) and each other language is its own <file>.i18n.<lang>.js file next to them, fetched the first time a card or the panel needs it. Home Assistant loads the card on every dashboard, so each page used to download and parse all 22 languages to use one. The cards and panel are defined once the page's language has arrived (a few milliseconds), so they render translated from the start.

Maintenance

• The Marketplace now installs the release zip (zip_release), like the other ha-* integrations: the split files are only in it.
• The repository keeps every language in the sources: the release runs scripts/split-frontend.mjs before building the zip, and the Validate workflow checks the split on a copy (every table is rebuilt from the split files and compared).