Rules-based browser launcher for TUI + GNOME.
switchyard.aly.codes
tui
gome
bowser
go
nix: add home-manager module
Aly Raffauf
(Jun 22, 2026, 1:09 PM EDT)
1072f1ad
74ff640e
+119
-1
+47
flake/hm-module.nix
+47
flake/hm-module.nix
···
1
+
self: {
2
+
pkgs,
3
+
config,
4
+
lib,
5
+
...
6
+
}: let
7
+
cfg = config.programs.switchyard;
8
+
toml = pkgs.formats.toml {};
9
+
in {
10
+
options.programs.switchyard = {
11
+
enable = lib.mkEnableOption "Switchyard browser launcher";
12
+
13
+
package = lib.mkPackageOption self.packages.${pkgs.system} "switchyard" {};
14
+
15
+
setAsDefaultBrowser = lib.mkOption {
16
+
type = lib.types.bool;
17
+
default = true;
18
+
description = ''
19
+
Register switchyard as the default handler for http(s) and text/html via {manpage}`home-configuration.nix(5)`'s {option}`xdg.mimeApps`.
20
+
'';
21
+
};
22
+
23
+
settings = lib.mkOption {
24
+
type = toml.type;
25
+
default = {};
26
+
description = ''
27
+
Contents of {file}`$XDG_CONFIG_HOME/switchyard/config.toml`.
28
+
29
+
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`.
30
+
'';
31
+
};
32
+
};
33
+
34
+
config = lib.mkIf cfg.enable {
35
+
home.packages = [cfg.package];
36
+
37
+
xdg.configFile."switchyard/config.toml" = lib.mkIf (cfg.settings != {}) {
38
+
source = toml.generate "switchyard-config.toml" cfg.settings;
39
+
};
40
+
41
+
xdg.mimeApps.defaultApplications = lib.mkIf cfg.setAsDefaultBrowser {
42
+
"x-scheme-handler/http" = ["io.github.alyraffauf.Switchyard.desktop"];
43
+
"x-scheme-handler/https" = ["io.github.alyraffauf.Switchyard.desktop"];
44
+
"text/html" = ["io.github.alyraffauf.Switchyard.desktop"];
45
+
};
46
+
};
47
+
}
+2
flake/packages.nix
+2
flake/packages.nix
+67
website/src/content/docs/home-manager.md
+67
website/src/content/docs/home-manager.md
···
1
+
---
2
+
title: home-manager
3
+
description: Install Switchyard and register it as the default browser via home-manager.
4
+
order: 22
5
+
---
6
+
7
+
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`.
8
+
9
+
## Setup
10
+
11
+
Add the flake to your inputs and import the module:
12
+
13
+
```nix
14
+
# flake.nix
15
+
{
16
+
inputs.switchyard.url = "github:alyraffauf/switchyard";
17
+
# ...
18
+
outputs = { self, nixpkgs, home-manager, switchyard, ... }: {
19
+
homeConfigurations.you = home-manager.lib.homeManagerConfiguration {
20
+
pkgs = nixpkgs.legacyPackages.x86_64-linux;
21
+
modules = [
22
+
switchyard.homeManagerModules.switchyard
23
+
./home.nix
24
+
];
25
+
};
26
+
};
27
+
}
28
+
```
29
+
30
+
```nix
31
+
# home.nix
32
+
{ ... }: {
33
+
programs.switchyard = {
34
+
enable = true;
35
+
setAsDefaultBrowser = true;
36
+
};
37
+
}
38
+
```
39
+
40
+
## Options
41
+
42
+
- **`enable`** *(bool, default `false`)* — Install Switchyard and enable the module.
43
+
- **`package`** *(package, default `switchyard`)* — The Switchyard derivation to install.
44
+
- **`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`.
45
+
- **`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.
46
+
47
+
## Declarative Configuration
48
+
49
+
`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:
50
+
51
+
```nix
52
+
programs.switchyard.settings = {
53
+
favorite_browser = "firefox";
54
+
remove_tracking_parameters = true;
55
+
rules = [
56
+
{
57
+
name = "work";
58
+
browser = "chromium";
59
+
conditions = [ { type = "domain"; pattern = "corp.example.com"; } ];
60
+
}
61
+
];
62
+
};
63
+
```
64
+
65
+
> **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.
66
+
67
+
See the [configuration reference](/docs/configuration/) for the full schema.
+3
-1
website/src/content/docs/nixos-flatpak.md
+3
-1
website/src/content/docs/nixos-flatpak.md
···
4
4
order: 25
5
5
---
6
6
7
-
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.
7
+
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.
8
+
9
+
On NixOS, browser desktop files live in `/run/current-system/sw/share/applications`. That path is not visible inside Flatpak by default.
8
10
9
11
To expose them to Switchyard, add the path to the Flatpak sandbox and include it in the XDG application search path:
10
12