Caelestia Shell

Caelestia-Shell is a desktop shell made for Wayland, specifically for the Hyprland compositor.

Installation

Caelestia is currently not available from nixpkgs. The only way to install Caelestia on NixOS is through Flakes.

❄︎ flakes.nix

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

    caelestia-shell = {
      url = "github:caelestia-dots/shell";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = inputs@{ self, nixpkgs, ... }: {
    nixosConfigurations.example = nixpkgs.lib.nixosSystem {
      specialArgs = { inherit inputs; };
      modules = [
        # ... other modules
        ./caelestia.nix
      ];
    };
  };
}

Without home-manager, the shell can be installed using the system packages :

❄︎ caelestia.nix

{ pkgs, inputs, ... }:
{
  environment.systemPackages = with pkgs; [
    inputs.caelestia-shell.packages.${pkgs.stdenv.hostPlatform.system}.default
  ];
}

We can also use the Home Manager module :

❄︎ caelestia.nix

{ pkgs, inputs, ... }:
{
  home-manager.users.foobar = {
    # import the home manager module
    imports = [
      inputs.caelestia.homeModules.default
    ];

    programs.caelestia = {
      enable = true;
      cli.enable = true; # Also adds caelestia-cli to path
    };
  };
}

Configuration

Three options are available :

1. Non-declarative : edit the ~/.config/caelestia/shell.jsonfile, following https://github.com/caelestia-dots/shell#example-configuration
2. Home-manager : you can use programs.caelestia.settingsto set each value through Nix, following the above schema. This can cause issues with the GUI settings.
3. Symlink copy : You can link the previously mentioned shell.json file to your nix config directory with mkOutOfStoreSymlink :
   ❄︎ caelestia.nix

   xdg.configFile."caelestia"={
       source = config.lib.file.mkOutOfStoreSymlink "${dotfiles}/caelestia";
       force = true;
       recursive = true;
    };
   

Starting the shell

Once the shell is installed, you should be able to launch it by executing caelestia shell -d.

To launch it automatically, you can add the following to your Hyprland config :

≡︎ hyprland.lua

hl.on("hyprland.start", function()
    hl.exec_cmd("caelestia shell -d")
end)

Or, for Hyprland < 0.55 :

≡︎ hyprland.conf

exec-once = caelestia shell -d

Troubleshooting

In some cases, the shell can become unresponsive or take a long time to load. If systemd-analyze blame | head -10 doesn't show any blocking programs, it can be due to a large number of notifications. In order to clear them, you can run caelestia shell notifs clear.