feat(#2422): add Nix flake package and NixOS module

README.md

@@ -54,6 +54,7 @@ This gives you nearly **1:1 parity with Hermes CLI from a convenient web UI** wh
 - [Quick start](#quick-start) — clone + `bootstrap.py` / `start.sh` / `ctl.sh`
 - [Features](#features) — chat, sessions, workspace, voice, profiles, security, themes, panels, mobile
 - [Configuration & access](#configuration--access) — auto-discovery, overrides, remote/Tailscale/phone, manual launch
+- [Nix flake/module](#nix-flake-and-nixos-module) — declarative install and service
 - [Docker](#docker) — single- and multi-container deploys
 - [Running tests](#running-tests)
 - [Architecture](#architecture) — backend/frontend layout, state dir
@@ -378,6 +379,63 @@ Extension deployments can inspect sanitized, authenticated diagnostics at `GET /
 
 ---
 
+### Nix flake and NixOS module
+
+Hermes WebUI has a Nix flake package and a NixOS service module so you can run it declaratively.
+
+Install the latest package with:
+
+```bash
+nix shell github:nesquena/hermes-webui#default
+```
+
+Use this flake input in your system configuration:
+
+```nix
+inputs.hermes-webui.url = "github:nesquena/hermes-webui";
+```
+
+Then add the module and configure it in `nixosModules`:
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    hermes-webui.url = "github:nesquena/hermes-webui";
+  };
+
+  outputs = { self, nixpkgs, hermes-webui, ... }: {
+    nixosConfigurations.<host> = nixpkgs.lib.nixosSystem {
+      modules = [
+        hermes-webui.nixosModules.default
+      ];
+    };
+  };
+}
+```
+
+Service example:
+
+```nix
+services.hermes-webui = {
+  enable = true;
+  host = "0.0.0.0";
+  port = 8787;
+  stateDir = "/var/lib/hermes-webui";
+  agent.dir = "/var/lib/hermes/hermes-agent";
+  environmentFiles = [ "/run/secrets/hermes-webui.env" ];
+};
+```
+
+Keep the module default host at `127.0.0.1`. Set `host = "0.0.0.0"` only when you also provide auth, for example `HERMES_WEBUI_PASSWORD` via `environmentFiles`.
+
+You can also set `agent.package` instead of `agent.dir` when you are using a compatible Hermes Agent package layout. The module derives `HERMES_WEBUI_AGENT_DIR` from `<pkg>/share/hermes-agent` and sets `HERMES_WEBUI_PYTHON` from the package's `passthru.hermesVenv` interpreter so bootstrap can use agent dependencies without creating a local `.venv`.
+
+The module maps directly onto existing WebUI environment variables, including:
+`HERMES_WEBUI_HOST`, `HERMES_WEBUI_PORT`, `HERMES_WEBUI_STATE_DIR`, `HERMES_HOME`, `HERMES_WEBUI_AGENT_DIR`, and `HERMES_WEBUI_PYTHON`.
+
+Set `environmentFiles` for secrets like API keys. Protected WebUI runtime keys from the module are rejected there, so keep host, port, state, and agent wiring in the module options. Keep reverse proxy and TLS configuration in your surrounding deployment module because those details are deployment-specific.
+
 ### Remote access (SSH tunnel, Tailscale, phone)
 
 The server binds to `127.0.0.1` by default. To reach it from another machine use an SSH tunnel (`ssh -N -L 8787:127.0.0.1:8787 user@host`, which `start.sh` prints for you over SSH), or join your server and phone to a [Tailscale](https://tailscale.com) network and browse to `http://<server-tailscale-ip>:8787` with `HERMES_WEBUI_HOST=0.0.0.0` + `HERMES_WEBUI_PASSWORD` set. Full walkthrough (incl. a community ARM64-Android field report): [`docs/remote-access.md`](docs/remote-access.md).