Home-Manager Module

If you use Nix, modde’s home-manager module lets you declare your mod profiles as code. It is built directly on the flake’s package output, and on every home-manager switch it runs an activation script that drives the modde CLI to install and deploy the profiles you declare. This is one powerful option for Nix users; it sits alongside the cross-platform settings file & environment, which is how everyone configures modde imperatively (and the only thing you need if you do not use Nix — manage preferences there and drive modde with the CLI). This page documents every option the module exposes, the validation assertions it enforces, the per-tool settings schemas, and several complete worked examples.

The option source is nix/hm-module.nix; the typed tool-settings schema is generated into nix/tool-schema.nix by modde dev export-tool-schema. To import the module, see Installation → Flake input + home-manager module.

Top-level options

programs.modde.enable

Whether to enable the modde game mod manager. When false, the module adds nothing to your closure and runs no activation work.

• Type: bool
• Default: false

programs.modde.package

The modde package to use. Defaults to the flake’s modde package for your system, which puts both modde (CLI) and modde-ui (GUI) on PATH. Override it to pin a specific build or substitute a patched package.

• Type: package
• Default: flake.packages.${pkgs.system}.modde

programs.modde.nexus.apiKeyFile

Path to a file containing your Nexus Mods API key. The activation script exports its path as the NEXUS_API_KEY_FILE environment variable, which modde resolves late in its API-key lookup chain — making it sops-nix / agenix friendly, since the secret never enters the Nix store.

• Type: null or path
• Default: null

programs.modde.nexus.apiKeyFile = config.sops.secrets.nexus-api-key.path;

programs.modde.profiles

An attribute set of mod profiles to manage. The attribute name is the profile name modde uses for --profile. Each value is a profile submodule.

• Type: attrsOf profile submodule
• Default: {}

The profile submodule

Each entry under programs.modde.profiles.<name> accepts the following options.

profiles.<name>.game

Game identifier string, passed to the CLI as --game. This is a free-form string in the module — modde validates it at runtime — so generic / user-defined games declared via modde game add and a GameSpec TOML work here too.

• Type: str
• Required: yes

The 15 shipping games use identifiers such as "skyrim-se", "skyrim-ae", "fallout4", "fallout76", "starfield", "cyberpunk2077", and "stellar-blade". See Supported games for the full, authoritative list of built-in identifiers.

profiles.<name>.gameDir

Runtime path to the game installation. modde does not install base games; it waits for a launcher-managed install. gameDir is required for Wabbajack modlists that reference local vanilla game files — for example a Skyrim SE list built from the vanilla Data directory.

• Type: null, path, or str
• Default: null

During activation, for Bethesda games (skyrim-se, skyrim-ae, fallout4, fallout76, starfield) the module additionally checks that gameDir contains a Data subdirectory before installing. If gameDir is unset, does not exist, or is missing the required Data directory, a Wabbajack profile prints an “awaiting game install” message and continues without failing.

profiles.<name>.installMode

Controls what home-manager activation does for this profile.

• Type: enum — "auto", "await-game", or "disabled"
• Default: "auto"

profiles.<name>.wabbajackList

Wabbajack modlist source. Mutually exclusive with nexusCollection (see Assertions).

• Type: null or submodule
• Default: null

Set exactly one source: either path, or both url and hash together. Use path when composing with requireFile or another fetcher that already materializes the .wabbajack file. When url + hash are used, the module fetches the modlist with pkgs.fetchurl at build time.

missingArchivePolicy is forwarded to the CLI as --missing-archive-policy when the profile is installed:

wabbajackList.manualArchives.<key>

Manual or Nexus archives that Wabbajack cannot download automatically (premium Nexus files, off-site mirrors, etc.). Each entry maps an archive to a local source file. The attribute key may be either the Wabbajack xxh64 hex hash (16 hex characters) or a readable label, in which case hash must be set inside the entry.

During activation, every entry with a non-null path is imported via modde wabbajack import-archive before the install runs. Required entries (those not marked optional) must set path, or the module fails an assertion.

profiles.<name>.nexusCollection

Nexus Collection source. Mutually exclusive with wabbajackList.

• Type: null or submodule
• Default: null

profiles.<name>.tools.<id>

Per-tool configuration for this profile, keyed by tool ID. Every tool slot defaults to null (unconfigured). Setting a tool to an attrset opts it in to the activation logic — enable = true runs modde tool enable, while leaving enable at its default of false runs modde tool disable during activation.

• Type: null or per-tool submodule
• Default: null (for each known tool ID)

Recognized tool IDs:

Common options on every tool submodule:

settings is typed for vkbasalt, gamemode, and reshade (each key is a distinct option with its own type, default, and validation derived from the Rust settings_schema()), and free-form for mangohud, optiscaler, and proton (an attrsOf accepting bool, int, float, str, or a list of strings). The per-tool key tables are in Tool settings reference below. The reserved keys _game_id and optiscaler_profile are ignored if set directly in settings (the module prints a warning and uses the dedicated profile option instead).

tools.<id>.release

Pins a downloaded release asset for a release-backed tool. Today only optiscaler supports release pinning (sourced from nix/release-supporting-tools.nix); setting release on any other tool fails an assertion.

Provide the asset either by path or by url + hash (the two are mutually exclusive). When url + hash are set the module materializes the asset with pkgs.fetchurl; with path you can hand it a requireFile result. During activation the asset is installed with modde tool install-release-from-path <id> --game <game> --tag <tag> --asset <asset> <src>.

tools.optiscaler.release = {
  tag = "v0.7.7";
  asset = "OptiScaler_v0.7.7.7z";
  path = pkgs.requireFile {
    name = "OptiScaler_v0.7.7.7z";
    sha256 = "0000000000000000000000000000000000000000000000000000";
    url = "https://github.com/optiscaler/OptiScaler/releases";
  };
};

tools.optiscaler.profile

Selects an OptiScaler per-game preset. This option exists only on the optiscaler tool. Its type is dynamic: if the game has registered presets (see nix/optiscaler-profiles.nix), the option becomes an enum of those presets; if the game has no registered presets, setting profile to a non-null value fails an assertion.

• Type: null, str, or enum of the game’s registered presets
• Default: null

Currently stellar-blade registers the community-dxgi preset; other games have no registered presets yet. The chosen preset is forwarded to the CLI as the optiscaler_profile=<preset> setting.

Assertions

The module evaluates a set of assertions per profile and per configured tool. Each is reported with a programs.modde.profiles.<name>... message so failures point straight at the offending option.

Tool settings reference

The tables below enumerate every key in the typed and notable free-form tool schemas, generated from nix/tool-schema.nix. Every key defaults to null (unset → modde uses its own default), and each typed key is validated to its declared type during evaluation.

vkbasalt (typed)

gamemode (typed)

gamemode exposes no typed settings keys — its schema in tool-schema.nix is empty. Use tools.gamemode.enable = true; (and optionally applyOnActivation) to turn it on; there are no per-key settings to configure.

reshade (typed)

optiscaler (free-form)

optiscaler settings are free-form (passed through to modde), but the schema documents the recognized keys and their accepted values:

proton (free-form, typed values)

proton settings are free-form, but most keys are boolean environment-variable toggles. Notable typed keys:

The remaining proton_*, radv_*, mesa_*, glx_*, enable_*, staging_*, and steamdeck keys are booleans that export the matching environment variable (for example proton_enable_nvapi = true exports PROTON_ENABLE_NVAPI=1, proton_enable_wayland exports PROTON_ENABLE_WAYLAND=1, radv_perftest_rt exports RADV_PERFTEST=rt,emulate_rt). See nix/tool-schema.nix for the full list and the exact variable each one sets.

mangohud (free-form passthrough)

mangohud settings are free-form and forwarded to modde verbatim. The schema documents the full MangoHud key surface (fps, gpu_temp, cpu_temp, frametime, position, font_size, background_alpha, fps_limit, toggle_hud, and dozens more), but no key is constrained by the Nix type system beyond the free-form value types (bool, int, float, str, list of str). For example:

tools.mangohud = {
  enable = true;
  settings = {
    fps = true;
    gpu_temp = true;
    cpu_temp = true;
    frametime = true;
    position = "top-left";
    font_size = 20;
  };
};

Worked examples

Wabbajack Skyrim profile with gameDir and await-game

A complete Skyrim SE Wabbajack list, declared before the game is installed. With installMode = "await-game", the first rebuild prints the next setup step and does nothing else; once Steam has installed the game, switch to installMode = "auto" and set gameDir, and the next rebuild installs and deploys the list. This example also pins a manual (premium-Nexus) archive.

{ config, ... }:
{
  programs.modde = {
    enable = true;
    nexus.apiKeyFile = config.sops.secrets.nexus-api-key.path;

    profiles.lotf = {
      game = "skyrim-se";
      installMode = "auto";  # flip from "await-game" once the game exists
      gameDir = "/home/me/.local/share/Steam/steamapps/common/Skyrim Special Edition";
      wabbajackList = {
        url = "https://example.com/legends-of-the-frost.wabbajack";
        hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
        missingArchivePolicy = "fail";
        manualArchives = {
          # Keyed by a readable label, so `hash` is required:
          unofficial-patch = {
            hash = "0123456789abcdef";
            path = "/home/me/Downloads/USSEP.7z";
          };
          # An optional archive — activation may omit affected outputs if absent:
          optional-enb = {
            hash = "fedcba9876543210";
            optional = true;
          };
        };
      };
    };
  };
}

Nexus Collection Cyberpunk profile

programs.modde.profiles.cyberpunk-mods = {
  game = "cyberpunk2077";
  installMode = "auto";
  nexusCollection = {
    slug = "my-cyberpunk-collection";
    version = "2.1.0";
  };
};

MangoHud + OptiScaler with real settings

A Stellar Blade profile that turns on MangoHud with a real overlay layout and enables OptiScaler with its community-dxgi preset, real INI overrides, and a pinned release asset applied on every activation.

{ pkgs, ... }:
{
  programs.modde.profiles.stellar-blade = {
    game = "stellar-blade";
    installMode = "auto";
    gameDir = "/home/me/Games/StellarBlade";

    tools = {
      mangohud = {
        enable = true;
        settings = {
          fps = true;
          frametime = true;
          gpu_temp = true;
          cpu_temp = true;
          gpu_load_change = true;
          position = "top-left";
          font_size = 20;
          background_alpha = 0.4;
        };
      };

      optiscaler = {
        enable = true;
        applyOnActivation = true;
        profile = "community-dxgi";
        settings = {
          source_mode = "github_release";
          proxy_dll = "dxgi.dll";
          fsr4_variant = "latest_fp8";
          "ini_overrides.FSR.UpscalerIndex" = "auto";
          "ini_overrides.Menu.Scale" = 1.2;
        };
        release = {
          tag = "v0.7.7";
          asset = "OptiScaler_v0.7.7.7z";
          path = pkgs.requireFile {
            name = "OptiScaler_v0.7.7.7z";
            sha256 = "0000000000000000000000000000000000000000000000000000";
            url = "https://github.com/optiscaler/OptiScaler/releases";
          };
        };
      };
    };
  };
}

With applyOnActivation = true, the release asset is written into the game directory every time home-manager switches to the profile, keeping the pin in sync automatically. Leave it off if you prefer to run modde tool apply by hand.

sops-nix apiKeyFile

Keep the Nexus API key out of the Nix store entirely by pointing apiKeyFile at a sops-nix (or agenix) secret. The module exports it as NEXUS_API_KEY_FILE during activation, which modde reads through its API-key precedence chain.

{ config, ... }:
{
  sops.secrets.nexus-api-key = {
    sopsFile = ./secrets.yaml;
    # mode/owner default to the activating user
  };

  programs.modde = {
    enable = true;
    nexus.apiKeyFile = config.sops.secrets.nexus-api-key.path;
    profiles.cyberpunk-mods = {
      game = "cyberpunk2077";
      nexusCollection = {
        slug = "my-cyberpunk-collection";
        version = "2.1.0";
      };
    };
  };
}

First install flow

modde does not install Steam or Heroic games. You can declare a profile before the game exists by omitting gameDir or setting installMode = "await-game". home-manager activation prints the next step and continues without failing.

After installing the game through Steam or Heroic, set gameDir to its install directory and use installMode = "auto". The next activation installs the Wabbajack profile (if its lock info is missing), then deploys it and applies the configured tools. For non-Wabbajack profiles, activation simply runs modde deploy and applies tools.

See also

• Settings file & environment — the imperative settings.toml, environment variables, and full Nexus key precedence
• Installation — install channels and how to import the module
• Supported games — authoritative game identifiers
• Tools guide — what each tool does at runtime
• Wabbajack guide — manual archives and modlist install