From 3128eb648bf6f5814e298f3bc37af6e66240afd0 Mon Sep 17 00:00:00 2001
From: Ilan Joselevich <personal@ilanjoselevich.com>
Date: Sun, 26 Apr 2026 19:05:27 +0300
Subject: [PATCH] nixos/home-assistant-matter-hub: init

---
 nixos/modules/module-list.nix                 |   1 +
 .../home-assistant-matter-hub.nix             | 100 ++++++++++++++++++
 2 files changed, 101 insertions(+)
 create mode 100644 nixos/modules/services/home-automation/home-assistant-matter-hub.nix

diff --git a/nixos/modules/module-list.nix b/nixos/modules/module-list.nix
index 746c8b05a964..17c41960c5b3 100644
--- a/nixos/modules/module-list.nix
+++ b/nixos/modules/module-list.nix
@@ -728,6 +728,7 @@
   ./services/home-automation/esphome.nix
   ./services/home-automation/evcc.nix
   ./services/home-automation/govee2mqtt.nix
+  ./services/home-automation/home-assistant-matter-hub.nix
   ./services/home-automation/home-assistant.nix
   ./services/home-automation/homebridge.nix
   ./services/home-automation/matter-server.nix
diff --git a/nixos/modules/services/home-automation/home-assistant-matter-hub.nix b/nixos/modules/services/home-automation/home-assistant-matter-hub.nix
new file mode 100644
index 000000000000..465707642f15
--- /dev/null
+++ b/nixos/modules/services/home-automation/home-assistant-matter-hub.nix
@@ -0,0 +1,100 @@
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+let
+  cfg = config.services.home-assistant-matter-hub;
+  settingsFormat = pkgs.formats.json { };
+  configFile = settingsFormat.generate "home-assistant-matter-hub.json" cfg.settings;
+in
+{
+  meta.maintainers = with lib.maintainers; [
+    kranzes
+    marie
+  ];
+
+  options.services.home-assistant-matter-hub = {
+    enable = lib.mkEnableOption "home-assistant-matter-hub, a Matter bridge for Home Assistant";
+
+    package = lib.mkPackageOption pkgs "home-assistant-matter-hub" { };
+
+    openFirewall = lib.mkOption {
+      type = lib.types.bool;
+      default = false;
+      description = ''
+        Whether to open the Matter commissioning ports (UDP/TCP 5540) in the
+        firewall.
+      '';
+    };
+
+    accessTokenFile = lib.mkOption {
+      type = lib.types.externalPath;
+      example = "/run/secrets/home-assistant-matter-hub-token";
+      description = ''
+        Path to a file containing a Home Assistant long-lived access token.
+        The file is loaded as a systemd credential and read into
+        `HAMH_HOME_ASSISTANT_ACCESS_TOKEN` at service start.
+      '';
+    };
+
+    settings = lib.mkOption {
+      type = lib.types.submodule {
+        freeformType = settingsFormat.type;
+        options = {
+          homeAssistantUrl = lib.mkOption {
+            type = lib.types.str;
+            example = lib.literalExpression "config.services.home-assistant.config.homeassistant.internal_url";
+            description = "HTTP URL of the Home Assistant instance to bridge.";
+          };
+
+          httpPort = lib.mkOption {
+            type = lib.types.port;
+            default = 8482;
+            description = "Port the web interface listens on.";
+          };
+        };
+      };
+      default = { };
+      example = lib.literalExpression ''
+        {
+          homeAssistantUrl = config.services.home-assistant.config.homeassistant.internal_url;
+        }
+      '';
+      description = ''
+        Configuration written to a JSON file and passed to
+        `home-assistant-matter-hub start --config`. Keys use camelCase, matching
+        the long-form CLI flags. See
+        <https://riddix.github.io/home-assistant-matter-hub/getting-started/installation#23-configuration-options>
+        for the full list of options.
+      '';
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    networking.firewall = lib.mkIf cfg.openFirewall {
+      allowedTCPPorts = [ 5540 ];
+      allowedUDPPorts = [ 5540 ];
+    };
+
+    systemd.services.home-assistant-matter-hub = {
+      description = "Home Assistant Matter Hub";
+      documentation = [ "https://riddix.github.io/home-assistant-matter-hub/" ];
+      wantedBy = [ "multi-user.target" ];
+      after = [ "network.target" ];
+
+      script = ''
+        export HAMH_HOME_ASSISTANT_ACCESS_TOKEN=$(systemd-creds cat HAMH_HOME_ASSISTANT_ACCESS_TOKEN)
+        exec ${lib.getExe cfg.package} start --config=${configFile} --storage-location="$1"
+      '';
+      scriptArgs = "%S/home-assistant-matter-hub";
+
+      serviceConfig = {
+        LoadCredential = [ "HAMH_HOME_ASSISTANT_ACCESS_TOKEN:${cfg.accessTokenFile}" ];
+        DynamicUser = true;
+        StateDirectory = "home-assistant-matter-hub";
+      };
+    };
+  };
+}