Get started

Your first evening with Gloam

Boot the live session, learn a handful of keys, and install it when you are ready.

1 · The live session

Download the ISO, write it to a USB stick and boot from it. Pick Gloam … Live in the boot menu (it starts on its own after a few seconds). Gloam starts at its greeter over the Afterglow sea. The live user nixos has no password: press Enter and Shady opens. Nothing on your disks is touched.

Network: open a terminal and run nmtui to join Wi-Fi.
Sound: pavucontrol picks outputs and volume.
Firefox is installed; launch it from the launcher (Super + D).

In a VM without a GPU, Gloam renders on the CPU. It works, but the sea moves less smoothly than on real hardware.

2 · Getting around

Super is the Windows / Command key. The bar at the top shows workspaces, windows and the clock.

Keys	Does
`Super + Return`	Open a terminal (foot)
`Super + D`	Open the application launcher
`Super + 1 / 2 / 3`	Switch to the shore, studio or harbor workspace
`Super + Shift + 1 / 2 / 3`	Move the focused window to that workspace
`Super + Tab`	Focus the next window
`Super + Q`	Close the focused window
`Super + M / Super + Shift + M`	Maximize / fullscreen
`Super + O`	3D overview of every window
`Super + T / Super + Shift + T`	Next / previous hour of light
`Super + F`	First-person mode: walk among your windows
`Super + Space / Super + Shift + Space`	Unfold / fold every window
`Super + Shift + Escape`	Log out
`Ctrl + Alt + F2`	Switch to a text console (F1 back)

3 · Logging in and out

The greeter appears at boot and whenever you log out. In the live session the nixos user has no password: press Enter. Up and Down choose the user, Tab the session:

Shady: the full 3D desktop.
Shady (Safe Mode): the same desktop on wlroots’ conventional renderer, for when 3D misbehaves.

Logs live in the journal: journalctl -t shady for the session, -t shady-greeter for the greeter.

4 · Installing

A graphical installer is planned. Today, Gloam installs the NixOS way from the live session’s terminal. Partition and mount your disk under /mnt as described in the NixOS manual, then:

sudo nixos-generate-config --root /mnt
sudo nano /mnt/etc/nixos/flake.nix      # paste the flake below
sudo nixos-install --flake /mnt/etc/nixos#gloam
sudo reboot

/mnt/etc/nixos/flake.nix:

{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
  inputs.shady.url = "github:gloaming-dusk/shady";
  inputs.shady.inputs.nixpkgs.follows = "nixpkgs";

  outputs = { nixpkgs, shady, ... }: {
    nixosConfigurations.gloam = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./configuration.nix
        shady.nixosModules.default
        {
          programs.shady.enable = true;
          programs.shady.greeter.enable = true;
          networking.networkmanager.enable = true;
          nix.settings.experimental-features = [ "nix-command" "flakes" ];
          users.users.you = {
            isNormalUser = true;
            extraGroups = [ "wheel" "networkmanager" ];
          };
        }
      ];
    };
  };
}

Replace you with your user name and set its password with sudo nixos-enter --root /mnt -c 'passwd you' before rebooting. After the reboot the Gloam greeter asks for it. Upgrades are nix flake update and sudo nixos-rebuild switch --flake /etc/nixos#gloam; if one goes wrong, pick the previous generation in the boot menu.

5 · On an existing NixOS

Already running NixOS with flakes? Add the shady input and the module to your system, exactly as in the modules list above, and run nixos-rebuild switch. The Shady and Shady (Safe Mode) sessions appear in your display manager; with programs.shady.greeter.enable the Gloam greeter replaces it.

Everything the module does is in nix/module.nix; the Shady documentation covers configuration, rices and plugins.