alexandria/content/Hacks/liminalOS-docs.md

id	aliases	tags	title
liminalOS-docs		nixos nixpkgs liminalos linux	Documentation for liminalOS system distribution

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.