Gandalf

One compositor to rule your desktop.

Gandalf is a minimal Wayland compositor written in C, built on the neu-swc compositor library.

It manages windows, workspaces, input and layouts — nothing more. Bars, launchers, notifications, wallpapers and lock screens stay external programs, integrated through standard Wayland protocols.

Status: Gandalf is under active development and is not yet recommended as a primary compositor. The C rewrite currently provides the project scaffolding and CLI; the compositor runtime is being built milestone by milestone — see ROADMAP.md.

Features

Target feature set for version 1 (see docs/roadmap/v1.md for the exact scope):

• dynamic tiling (master-stack), monocle and floating layouts
• numbered workspaces with per-workspace or global layout modes
• runtime configuration with atomic hot reload — no recompilation
• configurable keybindings, mouse bindings and window rules
• gaps and borders
• layer-shell support for bars, launchers and shells
• IPC for status bars and scripts
• first-class NixOS packaging
• XWayland, if sufficiently stable

Everything beyond that is tracked in docs/roadmap/V2-ideas.md and docs/roadmap/V3-ideas.md.

Installation

NixOS / Nix (primary platform)

Gandalf is NixOS-first. Pick your installation style:

Option 1 — NixOS module (flakes) — recommended

Add Gandalf as a flake input and import the NixOS module:

{
  inputs.gandalf.url = "https://forgejo.ftmahringer.com/FTMahringer/gandalf-wc";

  outputs = { nixpkgs, gandalf, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      modules = [
        gandalf.nixosModules.gandalf
        {
          programs.gandalf = {
            enable = true;
            # package = gandalf.packages.x86_64-linux.default;
            # xwayland.enable = true;
          };
        }
      ];
    };
  };
}

The nixosModules.gandalf output lands with the 0.8 milestone (roadmap/V1/0.8.md); until then use option 3.

Option 2 — Home Manager

For managing Gandalf per user, including the runtime configuration file:

{
  inputs.gandalf.url = "https://forgejo.ftmahringer.com/FTMahringer/gandalf-wc";

  outputs = { home-manager, gandalf, ... }: {
    homeConfigurations.me = home-manager.lib.homeManagerConfiguration {
      # ...
      modules = [
        {
          home.packages = [ gandalf.packages.x86_64-linux.default ];
        }
      ];
    };
  };
}

A dedicated Home Manager module (declarative config.conf generation) is planned; the runtime configuration file stays editable and reloadable either way.

Option 3 — Plain build / profile install

No modules, just the package:

# build
nix build

# or run directly
nix run

# or install into your profile
nix profile install

For development:

devenv shell
meson setup build
ninja -C build

The flake provides packages.${system}.gandalf, apps.${system}.gandalf, and devShells.${system}.default.

Arch Linux (community-supported, later)

Not packaged yet. Build from the repository once the compositor runtime and its dependencies land:

sudo pacman -S --needed base-devel meson ninja pkgconf wayland libxkbcommon pixman
meson setup build
ninja -C build
sudo ninja -C build install

neu-swc is not in the Arch repositories; it must be built from source or provided through the pinned Nix environment.

Debian / Ubuntu (community-supported, later)

Not packaged yet. Build from the repository:

sudo apt-get install build-essential meson ninja-build pkg-config \
    libwayland-dev libxkbcommon-dev libpixman-1-dev
meson setup build
ninja -C build
sudo ninja -C build install

neu-swc must be built from source until distribution packages exist.

Fedora (community-supported, later)

Not packaged yet. Build from the repository:

sudo dnf install gcc meson ninja-build pkgconf-pkg-config \
    wayland-devel libxkbcommon-devel pixman-devel
meson setup build
ninja -C build
sudo ninja -C build install

neu-swc must be built from source until distribution packages exist.

Other distributions

Gandalf is NixOS-first, not NixOS-only: the compositor itself has no Nix-specific runtime behavior. Any Linux system with a C23 compiler, Meson, and the dependencies below can build it. Packaging help for other distributions is welcome once the v1 runtime exists.

Dependencies

Current build dependencies:

• C23 compiler (GCC or Clang)
• Meson ≥ 1.10 and Ninja
• pkg-config

Runtime dependencies (used by the compositor baseline):

• neu-swc (compositor library, pinned in Nix)
• neuwld (through neu-swc)
• wayland, xkbcommon, pixman

Usage

gandalf --version   # print the version and exit
gandalf --help      # print usage
gandalf             # start the compositor

The installed gandalf command is a launcher wrapper: it sets up the neu-swc launch environment, starts swc-launch (which must be installed setuid root — on NixOS configure a security.wrappers.swc-launch entry, elsewhere sudo install -m 4755 -o root -g root <neuswc>/bin/swc-launch /usr/local/bin/swc-launch), and tees runtime logs to ~/.local/state/gandalf/gandalf.log (or $XDG_STATE_HOME/gandalf/) so startup and shutdown evidence survives the VT handoff. Start it as the logged-in user, never with sudo, from a free TTY.

Starting the compositor currently requires a real VT/DRM seat; nested Wayland sessions are not supported by neu-swc yet. Configuration and keybindings will be documented as the runtime lands. The planned configuration and command surface is defined in docs/architecture/configuration.md and the legacy parity inventory in docs/migration/legacy-feature-inventory.md.

Documentation

The documents in this repository are the source of truth for the C architecture. Start with:

1. docs/project/principles.md
2. docs/architecture/overview.md
3. docs/architecture/ownership.md
4. ROADMAP.md and docs/roadmap/c-rewrite-plan.md
5. docs/development/reference-repositories.md

Contributing

See CONTRIBUTING.md. The short version: read AGENTS.md first, keep changes inside the active roadmap milestone, and never add application-specific integrations — support the standard protocol instead.

Contributors are listed on the Forgejo repository.

Attribution

Gandalf builds on neu-swc (MIT, Michael Forney) as its compositor library, with tohu and wsxwm as primary usage and architecture references. The historical Zig implementation is preserved under reference-repos/gandalf-wc-legacy/ as a source of requirements and tested behavior — it is not translated.

License

Gandalf is released under the MIT License. See LICENSE.