Documentation

Everything you need to install, configure and shape atlaswm into your workflow.

Welcome to the atlaswm documentation. atlaswm is a Wayland compositor built around an infinite 2D plane: windows are placed anywhere on an unbounded canvas, and your monitor is a viewport you pan across it in both X and Y.

This is the toolbox. The pages here walk through the mental model, installing and running atlaswm, and the primitives — planes, tags, scratchpads, groups, anchors, zoom/overview, binds, submaps and window rules — that you compose into the workflow you want.

New here? Read the mental model (the vocabulary that makes everything obvious), then install it and try the first run. When you're ready to shape it, the workflow recipes are copy-paste configs for niri-, driftwm-, i3/sway-like and spatial setups.

In this section

• Mental model — Plane, viewport, rows, columns, cells, tabs, splits and floats — the vocabulary that makes the keybinds obvious.
• Installation — Run atlaswm nested in a window for development, or install the flake and pick it at your greeter as a real GPU session.
• First run — Spawn, focus, move, pan, zoom — the handful of keys that make the plane click in the first five minutes.
• Configuration — One live-reloaded KDL file drives everything: the mod key, input, binds, submaps, appearance, animations, rules and more.
• Keybindings — The default binds, how to rebind them, the resize / planes submaps, and how mod "auto" picks Alt or Super.
• Concepts — Planes, tags, gather/summon scratchpads, the overview, anchors, marks, window rules and groups — the primitives you compose into a workflow.
• Integration — Bars and panels via wlr-layer-shell, the atlas-submap / atlas-plane waybar modules, and scripting atlaswm over IPC with atlasctl.
• Troubleshooting — NVIDIA EGL/dmabuf, cursor theme, nested-under-Hyprland quirks, screen sharing and the portal env, spawn latency — the things that bite first.
• Recipe: niri-like — One row, scroll columns along X — atlaswm as niri, in 2D. The horizontal scrollable strip, with the second dimension waiting when you want it.
• Recipe: driftwm-like — Disconnected clusters scattered on the canvas; pan, zoom and overview between them — the driftwm working-set model on a 2D plane.
• Recipe: i3 / sway-like — Planes as numbered workspaces, recursive h/v splits and WM-level tabs, familiar i3 binds — the manual-tiling feel on an infinite canvas.
• Recipe: spatial hub-and-satellite — A central hub with satellites scattered across one big plane; jump between them by named anchor or window mark. The workflow only an infinite plane makes possible.

Documentation is a work in progress — more pages land in Phase 2.