Installation

Run atlaswm nested in a window for development, or install the flake and pick it at your greeter as a real GPU session.

There are two ways to run atlaswm, and you'll use both: nested in a window under your current compositor (the everyday dev path), and as a standalone DRM/KMS session straight on the GPU (what you daily-drive). Same binary, same config — the backend is chosen at launch.

Nested (dev path)

The fastest way to try it. atlaswm opens as a window under your existing Wayland compositor (Hyprland, sway, GNOME, …) and runs the full thing inside it: tiling, planes, zoom, the lot. Mod defaults to Alt while nested (the host owns Super), so it never fights your host's binds.

With Nix flakes:

nix develop -c cargo run -p atlaswm        # opens the nested compositor window
nix develop -c cargo test --workspace      # the test gate

nix develop drops you into the dev shell with the Rust toolchain and the system libraries Smithay needs (libinput, libxkbcommon, udev, EGL/GBM, …).

Keyboard layout follows the standard XKB environment variables until you set one in the config:

XKB_DEFAULT_LAYOUT=fr nix develop -c cargo run -p atlaswm   # azerty

The terminal spawned by Alt+Return is $ATLASWM_TERM, falling back to foot / alacritty / kitty / weston-terminal.

Test nested first, always. Rendering, real clients and input feel can't be unit-tested — running it under your current compositor is how you see it work, with zero risk to your session.

Quick TTY session test

Before installing it as a greeter session, prove the DRM backend works on your hardware. scripts/test-drm.sh stops your display manager, runs atlaswm on the GPU, and restores the display manager when it exits:

scripts/test-drm.sh          # 120s; pass a number for longer, e.g. 300

Run it from a separate VT (Ctrl+Alt+F3), not from inside your desktop. Exit with Mod+Shift+e (quit), Ctrl+C, or a VT switch; it also auto-exits after the timeout, so you can't get stuck.

Install as a greeter session (NixOS flake)

The flake exposes a package that installs the atlaswm binary plus a share/wayland-sessions/atlaswm.desktop entry (its Exec is atlaswm --session), with the runtime libraries Smithay dlopens wrapped in. Add it as a flake input and put it on sessionPackages:

# flake inputs:
inputs.atlaswm.url = "github:elfangor/atlaswm";

# in your NixOS configuration:
services.displayManager.sessionPackages = [
  inputs.atlaswm.packages.${pkgs.system}.default
];

Rebuild, then pick atlaswm at your greeter. To just build the binary without installing a session:

nix build .#atlaswm      # → ./result/bin/atlaswm

On a real session, mod "auto" resolves Mod to Super — so Super+Return opens a terminal, Super+h/j/k/l moves focus, Super+Shift+e quits.

The session wrapper

The installed atlaswm is a wrapper that sets the XDG session identity (XDG_CURRENT_DESKTOP=atlaswm and friends) and points LD_LIBRARY_PATH at the runtime libs before exec'ing the real compositor with --session. That session identity matters for portals (it's what routes screen-share to the right backend — see Troubleshooting). The wrapper also redirects the session's stderr to $XDG_STATE_HOME/atlaswm/session.log (plus .old) so you have a log to read when something misbehaves.

NVIDIA notes

atlaswm is developed and daily-driven on an NVIDIA RTX 3080 (Ampere) on the nvidia-open kernel modules — the DRM backend works on that exact card. NVIDIA's EGL is provided by the system driver via /run/opengl-driver; no nixGL wrapping is needed in the session. nvidia-drm.modeset=1 should already be set if you run any Wayland compositor today. If GL clients fail to start with EGL allocation errors, see the NVIDIA section of Troubleshooting.

Cursor theme tip

The DRM backend draws its own cursor (the nested backend lets the host draw it), loading the XCursor theme from XCURSOR_THEME / XCURSOR_SIZE. If the cursor looks like a default X arrow, set those env vars to your theme (e.g. a catppuccin cursor) in your session environment so the compositor finds it.

What you get either way

Tiling on a pool of infinite planes (columns, rows, tabs, recursive splits), floating, fullscreen, panning in X/Y, keyboard and mouse resize, a zoom ladder ending in a fit-plane overview, wlr-layer-shell for bars/panels (waybar, eww, fuzzel), XWayland, screen sharing — all configurable, all live-reloaded.

Next: the first run, then configuration.