diff --git a/flake/hm-module.nix b/flake/hm-module.nix
new file mode 100644
index 0000000..e60fa29
--- /dev/null
+++ b/flake/hm-module.nix
@@ -0,0 +1,47 @@
+self: {
+  pkgs,
+  config,
+  lib,
+  ...
+}: let
+  cfg = config.programs.switchyard;
+  toml = pkgs.formats.toml {};
+in {
+  options.programs.switchyard = {
+    enable = lib.mkEnableOption "Switchyard browser launcher";
+
+    package = lib.mkPackageOption self.packages.${pkgs.system} "switchyard" {};
+
+    setAsDefaultBrowser = lib.mkOption {
+      type = lib.types.bool;
+      default = true;
+      description = ''
+        Register switchyard as the default handler for http(s) and text/html via {manpage}`home-configuration.nix(5)`'s {option}`xdg.mimeApps`.
+      '';
+    };
+
+    settings = lib.mkOption {
+      type = toml.type;
+      default = {};
+      description = ''
+        Contents of {file}`$XDG_CONFIG_HOME/switchyard/config.toml`.
+
+        Omitted keys fall back to switchyard's built-in defaults. Note that Switchyard overwrites this file on every in-app config change, so GUI edits will be lost on the next {command}`home-manager switch`.
+      '';
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    home.packages = [cfg.package];
+
+    xdg.configFile."switchyard/config.toml" = lib.mkIf (cfg.settings != {}) {
+      source = toml.generate "switchyard-config.toml" cfg.settings;
+    };
+
+    xdg.mimeApps.defaultApplications = lib.mkIf cfg.setAsDefaultBrowser {
+      "x-scheme-handler/http" = ["io.github.alyraffauf.Switchyard.desktop"];
+      "x-scheme-handler/https" = ["io.github.alyraffauf.Switchyard.desktop"];
+      "text/html" = ["io.github.alyraffauf.Switchyard.desktop"];
+    };
+  };
+}
diff --git a/flake/packages.nix b/flake/packages.nix
index 6ac03a3..e2c3e9b 100644
--- a/flake/packages.nix
+++ b/flake/packages.nix
@@ -1,4 +1,6 @@
 {inputs, ...}: {
+  flake.homeManagerModules.switchyard = import ./hm-module.nix inputs.self;
+
   perSystem = {
     pkgs,
     self',
diff --git a/website/src/content/docs/home-manager.md b/website/src/content/docs/home-manager.md
new file mode 100644
index 0000000..d0044b1
--- /dev/null
+++ b/website/src/content/docs/home-manager.md
@@ -0,0 +1,67 @@
+---
+title: home-manager
+description: Install Switchyard and register it as the default browser via home-manager.
+order: 22
+---
+
+Switchyard's flake exposes a [home-manager](https://nix-community.github.io/home-manager/) module that installs the package, optionally writes `~/.config/switchyard/config.toml`, and registers Switchyard as the default handler for `http(s)`/`text/html`.
+
+## Setup
+
+Add the flake to your inputs and import the module:
+
+```nix
+# flake.nix
+{
+  inputs.switchyard.url = "github:alyraffauf/switchyard";
+  # ...
+  outputs = { self, nixpkgs, home-manager, switchyard, ... }: {
+    homeConfigurations.you = home-manager.lib.homeManagerConfiguration {
+      pkgs = nixpkgs.legacyPackages.x86_64-linux;
+      modules = [
+        switchyard.homeManagerModules.switchyard
+        ./home.nix
+      ];
+    };
+  };
+}
+```
+
+```nix
+# home.nix
+{ ... }: {
+  programs.switchyard = {
+    enable = true;
+    setAsDefaultBrowser = true;
+  };
+}
+```
+
+## Options
+
+- **`enable`** *(bool, default `false`)* — Install Switchyard and enable the module.
+- **`package`** *(package, default `switchyard`)* — The Switchyard derivation to install.
+- **`setAsDefaultBrowser`** *(bool, default `true`)* — Register Switchyard as the default handler for `x-scheme-handler/http`, `x-scheme-handler/https`, and `text/html` via `xdg.mimeApps`.
+- **`settings`** *(TOML, default `{}`)* — Contents of `~/.config/switchyard/config.toml`. Freeform; any key from Switchyard's `Config` struct is accepted, omitted keys fall back to built-in defaults.
+
+## Declarative Configuration
+
+`settings` is a freeform TOML value — any key Switchyard understands is accepted, and new fields added to Switchyard's `Config` struct work without changes to the module:
+
+```nix
+programs.switchyard.settings = {
+  favorite_browser = "firefox";
+  remove_tracking_parameters = true;
+  rules = [
+    {
+      name = "work";
+      browser = "chromium";
+      conditions = [ { type = "domain"; pattern = "corp.example.com"; } ];
+    }
+  ];
+};
+```
+
+> **Warning:** Switchyard overwrites `config.toml` on every in-app config change. Edits made through the GUI will be lost on the next `home-manager switch`. Treat `settings` as declarative: pick one source of truth.
+
+See the [configuration reference](/docs/configuration/) for the full schema.
diff --git a/website/src/content/docs/nixos-flatpak.md b/website/src/content/docs/nixos-flatpak.md
index bf58e49..52ff08a 100644
--- a/website/src/content/docs/nixos-flatpak.md
+++ b/website/src/content/docs/nixos-flatpak.md
@@ -4,7 +4,9 @@ description: Allow the Flatpak build of Switchyard to find host browser desktop
 order: 25
 ---
 
-On NixOS, browser desktop files live in `/run/current-system/sw/share/applications`. That path is not visible inside Flatpak by default, so Switchyard may not detect host browsers.
+NixOS users should consider using the Nix package and/or the [home-manager module](/docs/home-manager/). If you do use the Flatpak, Switchyard may not be able to accurately discover your installed browsers.
+
+On NixOS, browser desktop files live in `/run/current-system/sw/share/applications`. That path is not visible inside Flatpak by default.
 
 To expose them to Switchyard, add the path to the Flatpak sandbox and include it in the XDG application search path: