📚 Alexandria

Documentation for liminalOS system distribution

9 min read

This is documentation for the liminalOS system distribution, a Linux distribution built on NixOS.

The goal of liminalOS is to provide an opinionated desktop environment and system for those too lazy to spend 100 hours ricing their NixOS system.

To that end, a NixOS module and home manager module are provided such that it is possible to configure an entire operating system powered by a riced out desktop environment built on Hyprland in a few lines. These modules come with verified versions of all of the other flake input modules that compose liminalOS, so that you don’t have to manage and version Home Manager, stylix, agenix, etc yourself.

Central to this system is the liminalOS option that is added to both home manager and NixOS. It is designed to be used alongside a very minimal NixOS and Home Manager configuration to define the entire liminalOS system.

You only need to set up basic things like a minimal flake.nix, configuration.nix, and home.nix, where you need only set up a basic user (in both NixOS and HM) and boot loader configuration. The rest of the higher level system features will be handled by the liminalOS abstraction.

Something like this is sufficient to bootstrap a liminalOS system. It can be dropped into any existing NixOS system and be used alongside an existing configuration.

# file: configuration.nix
{
  liminalOS = {
    config.allowUnfree = true;
    defaultEditor = pkgs.helix;
    formFactor = "desktop";
    theming = {
      # place your desired wallpaper in your configuration repo and watch your
      # system theme itself
      wallpaper = ./wallpaper.jpg;
    };
    system.graphics.nvidia.enable = true;
    extras.gaming.enable = true;
  };
 
  # Set up a user
  users.users.default-user = {
    isNormalUser = true;
    description = "Default liminalOS user!";
    extraGroups = [
      "networkmanager"
      "wheel"
    ];
    shell = pkgs.fish;
  };
 
  home-manager.users.default-user = {
    # in this simple example, the content of ./home.nix is an import of the
    # liminalOS home manager module
    imports = [ ./home.nix ];
  };
  home-manager.extraSpecialArgs = { inherit inputs; };
 
  # Set your time zone
  time.timeZone = "America/Los_Angeles";
 
  # Bootloader and kernel.
  boot = {
    loader = {
      efi.canTouchEfiVariables = true;
      timeout = 15;
      systemd-boot = {
        enable = true;
      };
    };
  };
}

The recommended way to start using liminalOS is to first install NixOS and then install liminalOS over it. It is trivially possible in theory to generate liminalOS installer ISOs but this has not yet been developed. Hackers welcome to try!

You can generate a basic set of NixOS configuration files that deploy liminalOS using:

nix flake init -t github:youwen5/liminalOS

Make sure you read the comments and edit the desired options before nixos-rebuild!

IMPORTANT

You should at the very least set the hostname, username of your account, and most importantly include the hardware-configuration.nix file generated at /etc/nixos in the same directory as configuration.nix! If you don’t have this file anymore, run nixos-generate-config to recreate it at /etc/nixos.

Full liminalOS module options

These are all of the available options set by liminalOS, automatically generated from liminalOS’ modules. Keep in mind that many of these are enabled automatically when liminalOS.enable is set to true, but they are still available for fine-grained customization.

liminalOS.enable

Whether to enable liminalOS’s default modules and options for Linux.

Type: boolean

Default: true

Declared by:

liminalOS.config.allowUnfree

Whether to enable some proprietary packages required by certain liminalOS modules. This does not set allowUnfree for the whole system, it merely allows the installation of a few proprietary packages such as Nvidia drivers, etc. You should still set this option even if you already set nixpkgs.config.allowUnfree for the whole system since it tells liminalOS it can enable certain options that require proprietary packages.

Type: boolean

Default: false

Declared by:

liminalOS.config.extraUnfreePackages

Packages to enable in allowUnfreePredicate

Type: list of string

Default: [ ]

Declared by:

liminalOS.darwin.enable

Whether to enable liminalOS’s default modules and options for Darwin.

Type: boolean

Default: false

Declared by:

liminalOS.defaultEditor

Default text editor that will be installed and set as $EDITOR. Set to null to disable setting and installing default text editor.

Type: null or package

Default: <derivation neovim-0.10.3>

Declared by:

liminalOS.desktop.enable

Whether to enable the liminalOS desktop environment.

Type: boolean

Default: true

Declared by:

liminalOS.desktop.greeter.enable

Whether to enable and set up tui-greet, the default greeter for liminalOS.

Type: boolean

Default: true

Declared by:

liminalOS.desktop.greeter.command

Command for the greeter to execute to launch the desktop. If the liminalOS Hyprland Desktop is enabled, defaults to Hyprland.

Type: string

Default: "Hyprland"

Declared by:

liminalOS.desktop.hyprland.enable

Whether to enable Hyprland. Sets up a default configuration at the system and user level, and installs xdg-desktop-portal-gtk.

Type: boolean

Default: true

Declared by:

liminalOS.extras.distrobox.enable

Whether to enable distrobox and podman.

Type: boolean

Default: false

Example: true

Declared by:

liminalOS.extras.gaming.enable

Whether to enable gaming.

Type: boolean

Default: false

Example: true

Declared by:

liminalOS.extras.gaming.roblox.enable

Whether to install the Roblox Sober flatpak automatically. Note that this will enable the nix-flatpak service and automatic flatpak updates.`

Type: boolean

Default: false

Declared by:

liminalOS.extras.gaming.utilities.gamemode.enable

Whether to enable gamemode.

Type: boolean

Default: false

Example: true

Declared by:

liminalOS.extras.gaming.utilities.gamemode.gamemodeUsers

List of users to add to the gamemode group. Gamemode will likely not work unless you add your user to the group!

Type: list of string

Default: [ ]

Declared by:

liminalOS.extras.gaming.utilities.hamachi.enable

Whether to enable hamachi.

Type: boolean

Default: false

Example: true

Declared by:

liminalOS.flakeLocation

Absolute filepath location of the NixOS system configuration flake.

Type: null or path

Default: null

Declared by:

liminalOS.formFactor

Form factor of the machine. Adjusts some UI settings.

Type: null or one of “laptop”, “desktop”

Default: null

Declared by:

liminalOS.integrateHomeManager

Whether to activate home manager with default options. Keep in mind you still have to import the liminalOS home-manager module.

Type: boolean

Default: true

Declared by:

liminalOS.powersave

Whether to set some options to reduce power consumption (mostly Hyprland).

Type: boolean

Default: false

Declared by:

liminalOS.programs.flatpak.enable

Whether to enable Nix flatpak support with some fixes as well as declarative flatpak management.

Type: boolean

Default: false

Declared by:

liminalOS.programs.wine.enable

Whether to enable wine.

Type: boolean

Default: false

Example: true

Declared by:

liminalOS.system.audio.enable

Whether to set up PipeWire and default audio utilities.

Type: boolean

Default: true

Declared by:

liminalOS.system.audio.prod.enable

Whether to enable audio production.

Type: boolean

Default: false

Example: true

Declared by:

liminalOS.system.core.enable

Whether to enable core liminalOS system utilities and configurations (such as security policies, Nix options, etc)

Type: boolean

Default: true

Declared by:

liminalOS.system.core.bluetooth.enable

Whether to enable bluetooth and blueman.

Type: boolean

Default: true

Declared by:

liminalOS.system.core.nixSaneDefaults

Whether to set sane defaults for Nix, such as optimization and automatic garbage collection.

Type: boolean

Default: true

Declared by:

liminalOS.system.core.replaceSudoWithDoas

Whether to replace sudo with doas, the Dedicated OpenBSD Application Subexecutor. Doas is the preferred liminalOS setuid program.

Type: boolean

Default: true

Declared by:

liminalOS.system.core.suppressWarnings

Whether to enable suppress warnings.

Type: boolean

Default: false

Example: true

Declared by:

liminalOS.system.core.useNh

Whether to enable the nh cli (yet another Nix helper), a reimplementation of some core NixOS utilities like nix-collect-garbage and nixos-rebuild. If enabled, automatic garbage collection will use nh instead of nix-collect-garbage and will be able to garbage collect result symlinks.

Type: boolean

Default: true

Declared by:

liminalOS.system.core.waylandFixes

Whether to enable some Wayland fixes, like setting NIXOS_OZONE_WL to hint Electron apps to use the Wayland windowing system.

Type: boolean

Default: true

Declared by:

liminalOS.system.fonts.enable

Whether to set up some nice default fonts, including a Nerd Font, Noto Fonts, and CJK.

Type: boolean

Default: true

Declared by:

liminalOS.system.graphics.enable

Whether to set up basic graphics settings and options.

Type: boolean

Default: true

Declared by:

liminalOS.system.graphics.nvidia.enable

Whether to enable recommended nvidia drivers and configuration.

Type: boolean

Default: false

Example: true

Declared by:

liminalOS.system.graphics.nvidia.optimus-prime.enable

Whether to enable Nvidia OPTIMUS and PRIME.

Type: boolean

Default: false

Example: true

Declared by:

liminalOS.system.graphics.nvidia.optimus-prime.powerMode

Whether to use Nvidia OPTIMUS with maximum performance using the discrete graphics card, or to use offload mode to primarily use the integrated GPU and save power.

Type: one of “powersaving”, “performance”

Default: "performance"

Declared by:

liminalOS.system.graphics.nvidia.suppressUnfreeWarning

Whether to disable the assertion that warns the user if they try to enable proprietary nvidia drivers without setting allowUnfree.

Type: boolean

Default: false

Declared by:

liminalOS.system.networking.enable

Whether to enable networking features.

Type: boolean

Default: true

Declared by:

liminalOS.system.networking.backend

Which backend to use for networking. Default is wpa_supplicant with NetworkManager as a frontend. With iwd, iwctl is the frontend.

Type: one of “wpa_supplicant”, “iwd”

Default: "wpa_supplicant"

Declared by:

liminalOS.system.networking.cloudflareNameservers.enable

Whether to enable Cloudflare DNS servers.

Type: boolean

Default: false

Example: true

Declared by:

liminalOS.system.networking.firewallPresets.grimDawn

Whether to enable firewall ports for Grim Dawn.

Type: boolean

Default: false

Example: true

Declared by:

liminalOS.system.networking.firewallPresets.vite

Whether to enable firewall ports for Vite.

Type: boolean

Default: false

Example: true

Declared by:

liminalOS.system.printing.enable

Whether to set up default options for printing and printer discover on UNIX.

Type: boolean

Default: true

Declared by:

liminalOS.theming.enable

Whether to uniformly theme the entire system using Stylix.

Type: boolean

Default: true

Declared by:

liminalOS.theming.base16Scheme

Base 16 colorscheme from base16-schemes to override wallpaper generated colorscheme with. Set to null to use wallpaper generated scheme. Example: ${pkgs.base16-schemes}/share/themes/rose-pine.yaml

Type: null or path

Default: null

Declared by:

liminalOS.theming.plymouth.enable

Whether to enable plymouth and sane defaults.

Type: boolean

Default: true

Declared by:

liminalOS.theming.polarity

Whether to force colorscheme to be generated as light or dark theme. Set to null to automatically determine.

Type: null or one of “light”, “dark”

Default: null

Declared by:

liminalOS.theming.wallpaper

Path to wallpaper to set as background and generate system colorscehme from.

Type: anything

Default: "../../../hm/modules/common/shellenv/fastfetch/nixos-logo.png"

Declared by:

liminalOS.useEnUsLocale

Whether to use the en_US locale automatically

Type: boolean

Default: true

Declared by:

liminalOS.wsl.enable

Whether to enable WSL.

Type: boolean

Default: false

Example: true

Declared by:

Graph View

Backlinks