English | Русский
This is my personal Wayland shell on wlroots 0.20, for Arch Linux and Arch-based distributions. I built it for the way I work and I use it every day: my desktop is a terminal (foot), apps open on top of it fullscreen, and I use only black and white, square corners and no wallpaper.
Version 1.5.0.
Supported systems: Arch Linux and Arch-based distributions only (Manjaro, EndeavourOS, CachyOS, …). Other distributions are not supported.
I created all of this personally for myself, and I use this environment and these programs every day. I configured the terminal, keybindings, colors, scripts and dotfiles for my own workflow. When you install vlswm, you get exactly the environment I use personally. It is not a product or a universal desktop, and I do not try to make it one — change the config if something does not fit you.
Experimental project. I wrote it with AI help.
| Dashboard, black theme | Dashboard, white theme |
|---|---|
![]() |
![]() |
| Launcher, black theme | Launcher, white theme |
|---|---|
![]() |
![]() |
| Notification cards | Notifications panel |
|---|---|
![]() |
![]() |
The dots/ folder is my personal environment, tuned to the way I actually use VLSWM: my Neovim (dots/nvim), btop (dots/btop) and cava (dots/cava) configs, all monochrome and following the VLSWM theme, plus the vlswm-theme-watch user service that keeps btop and cava in sync with SUPER+T.
install.sh asks whether to install them and moves anything it replaces to a timestamped .backup directory. This is the environment I use personally (Zen browser, yazi, a full Neovim setup). If you install it, you get my setup, not a universal default.
| Neovim, black theme | Neovim, white theme |
|---|---|
![]() |
![]() |
| btop, black theme | btop, white theme |
|---|---|
![]() |
![]() |
| cava, black theme | cava, white theme |
|---|---|
![]() |
![]() |
- When I start vlswm, foot opens fullscreen as the base layer: I cannot close it. If it exits (for example
exitin fish), vlswm starts it again. - Any app I open appears on top, fullscreen. Windows are stacked.
SUPER+←/SUPER+→cycles windows.SUPER+Qcloses the focused window. The base foot cannot be closed.SUPER+ENTERopens a new terminal. The base (first) terminal cannot be closed; new windows are closed withSUPER+Q.SUPER+Dopens the launcher: a black (or white) rectangle in the center with an input field. Search only covers.desktopfiles (Name, GenericName, file name), case-insensitive. One best match is shown below the field;Enterlaunches it. If nothing matches, there is no suggestion andEnterdoes nothing. Apps withTerminal=trueopen in a separate foot window.Esccancels.SUPER+Ttoggles the theme: black ↔ white. The screen background, launcher frame and input field change. The foot theme changes in all terminal windows too: vlswm sendsSIGUSR1(black) orSIGUSR2(white) to every window, without restarting it.- Window animation: fade + 14 px rise on open and 10 px on close, 200 ms. The launcher appears instantly;
[launcher] durationsets its delay in ms (0 — no animation). - X11 apps work through
xwayland-satellite, started on first use. - Drag and drop works with pointer drags: tabs, files and other drag sources. The drag icon follows the cursor. While dragging,
SUPER+←/SUPER+→raises the next window, so you can drop onto another fullscreen app. - Dialogs (transient or fixed-size windows) open at their natural size and are centered; the parent window stays visible behind them. Fullscreen apps stay fullscreen.
- Cursors come from the system theme (
XCURSOR_THEME,XCURSOR_SIZE) and scale with[output] scale. Standard cursor shapes usewp_cursor_shape_v1, so GTK4 apps like Loupe get the same 24 px cursors; apps with custom cursor surfaces keep them. - Volume, screen brightness and keyboard backlight changes show a minimal inverted-theme vertical bar at the right edge, vertically centered.
I use zen-browser and recommend it for vlswm. It behaves predictably in a fullscreen window, and its menus and popups work correctly after the fixes in this release. I bound it to SUPER+Z in my default config.
SUPER+T changes the colors of my compositor, launcher and foot terminal. I do not touch other apps, so they may look off: some interfaces stay dark or light, some use their own palette. If an app looks wrong, I change its own theme.
- wlroots 0.20
wlr-protocols— protocol headers are generated from its XML at build time- wayland, xkbcommon, pixman, libinput, cairo, pango, pangocairo, libsystemd (sd-bus)
- Runtime:
foot(>= 1.28),fish,xwayland-satellite,wf-recorder(recording),grim,slurp,wl-clipboard(screenshots and clipboard),cliphist(clipboard history),brightnessctl(brightness),wireplumber(wpctl, volume),yazi,neovim,btop,cava(dotfiles) xdg-desktop-portal,xdg-desktop-portal-gtk— file pickers in GTK appsxdg-desktop-portal-termfilechooser(AUR) — opensyaziin file pickers; without it the GTK dialog is usedqt5-declarative— required by the Qt5 SDDM greeter for my themeqt6-declarative— Qt6 Quick, required byvlswm-lockand the lock screenqt6-wayland— Qt6 Wayland platform plugin; without itvlswm-lockcannot open a windowtree-sitter-cli— builds parsers for the Neovim config (nvim-treesitter)- Font
JetBrainsMono Nerd Font(or any other set in[launcher] font) zen-browser-bin(AUR) — my browser;install.shinstalls it throughparu-binoryay-binafter asking which helper to usemesa— software OpenGL, needed in virtual machines without 3D acceleration
cmake -B build
cmake --build buildRelease with LTO is the default. Binary: build/vlswm. Install: sudo ./install.sh — it builds Release and installs stripped copies to /usr/bin. This installs the same setup I use. For debugging: cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo.
Headless smoke test: ./scripts/vlswm-smoke-test starts vlswm with the headless backend, captures a 1280×720 frame with grim and checks a clean exit.
CMake generates the missing protocol headers from wlr-protocols and creates compatible copies of the wlroots headers where the C99 [static N] syntax is replaced with [N] — otherwise a C++ compiler on a clean Arch refuses to build the project. If a system protocol XML is missing or empty, the copy from protocols/ in the repository is used.
Run from a TTY or from an SDDM session named vlswm. Another config: vlswm -c /path/to/config.
install.sh also asks whether to install my personal dotfiles from dots/ (the Neovim, btop and cava configs I use) and enables the vlswm-theme-watch user service so btop and cava follow the VLSWM theme. It also asks which AUR helper to use (paru-bin or yay-bin) and installs zen-browser-bin through it. It also asks whether to install my SDDM theme; if yes, it clones Vlad175cm/vlswm-sddm-theme into vlswm-sddm-theme/ and runs its installer.
After installing, enable the SDDM service so it starts at boot and shows the login screen after a reboot:
sudo systemctl enable --now sddm.serviceWithout this, SDDM will not appear and the system will boot to a TTY.
sudo vlswm-updateThe command always installs the latest GitHub release: it looks up the newest tag, clones it into /opt/vlswm, builds it and replaces /usr/bin/vlswm, /usr/bin/vlswmstat, /usr/bin/vlswm-lock, the lock screen QML, the recording/screenshot scripts and the SDDM session file. After installing, it runs the freshly installed vlswm-update once more in --install-only mode, so files added in the new release are always installed even when the update started from an older script. It also refreshes the system environment configs (environment.d, fish conf and the file chooser portal configs) with a timestamped backup; ~/.config/vlswm/config, foot.ini and dots/ are not touched. It re-clones and reinstalls even when that release is already installed. Existing config values are never overwritten: if a release adds new options, they are appended to your config and the old file is saved as config.backup.YYYY-MM-DD-HHMMSS. Log out and back in to use the new binaries.
File: ~/.config/vlswm/config. Reload without restarting: SUPER+R.
I keep the default config in the repository hardware-agnostic, and it may gain new options over time; check config/config on GitHub after updating. Every release lists the new config keys.
Combos are written as MODIFIERS+KEY. Modifiers: SUPER, SHIFT, CTRL, ALT. One action may have several keys separated by commas.
[keybinds]
launcher = "SUPER+D"
lock = "SUPER+L"
close = "SUPER+Q"
reload = "SUPER+R"
exit = "SUPER+ESC"
theme = "SUPER+T"
focus_prev = "SUPER+RIGHT"
focus_next = "SUPER+LEFT"
file_manager = "SUPER+E"
terminal = "SUPER+ENTER"
restart_terminal = "SUPER+SHIFT+R"
record = "SUPER+ALT+R"
record_stop = "SUPER+ALT+S"
screenshot = "SUPER+SHIFT+A"
clipboard = "SUPER+SHIFT+V"
notifications = "SUPER+N"
zen = "SUPER+Z" # app: a key from [commands]
[commands]
zen = "zen-browser" # any app: name = command
record = "$HOME/.local/bin/vlswm-record start"
record_stop = "$HOME/.local/bin/vlswm-record stop"
screenshot = "$HOME/.local/bin/vlswm-screenshot"
[launcher]
terminal = "foot"
file_manager = "yazi"
font = "JetBrainsMono Nerd Font 16"
duration = 0 # ms; 0 = no animation
[theme]
foot = "~/.config/foot" # foot config directory
[animations]
duration = 200 # ms
curve = "ease-out" # linear, ease-in, ease-out, ease-in-out
[input]
repeat_delay = 200 # ms before the first repeat
repeat_rate = 40 # repeats per second
scroll_speed = 0.5 # scroll speed multiplier (touchpad and wheel)
layout = "us,ru" # keyboard layouts
layout_options = "grp:win_space_toggle" # SUPER+SPACE switches the layout
repeat = "focus_next, focus_prev"
[record]
audio = "mic" # mic | system | both
[xwayland]
satellite = "xwayland-satellite"
display = ":1"
[output]
scale = 1.0 # interface scale (1.0, 1.5, 2.0)The default config does not bind brightness, volume or the microphone: they depend on the machine. Add what you need:
[keybinds]
brightness_up = "XF86MonBrightnessUp"
brightness_down = "XF86MonBrightnessDown"
volume_up = "XF86AudioRaiseVolume"
volume_down = "XF86AudioLowerVolume"
volume_mute = "XF86AudioMute"
mic_toggle = "SUPER+ALT+M"
[commands]
brightness_up = "brightnessctl -q set 5%+"
brightness_down = "brightnessctl -q set 5%-"
volume_up = "wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+"
volume_down = "wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-"
volume_mute = "wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle"
mic_toggle = "$HOME/.local/bin/vlswm-mic"
[input]
repeat = "focus_next, focus_prev, volume_up, volume_down, brightness_up, brightness_down"Keyboard backlight on Macs: add kbd_brightness_up = "XF86KbdBrightnessUp" / kbd_brightness_down = "XF86KbdBrightnessDown" and commands with brightnessctl --device='smc::kbd_backlight' set 5%+ / 5%-.
- In
[commands]set a name and a command:name = "command". - In
[keybinds]set the same name and a key:name = "SUPER+X".
Apps do not repeat while a key is held. Only actions listed in [input] repeat repeat.
vlswm reads the base palette from [colors-dark] in ~/.config/foot/foot.ini, writes vlswm-theme.ini with the inverted palette in [colors-light] and adds an include=~/…/vlswm-theme.ini line to foot.ini. The base palette is re-read on start and on SUPER+R, so the colors in [colors-dark] matter. vlswm-theme.ini is generated and rewritten on every SUPER+R; editing it by hand is pointless.
On SUPER+T vlswm sends SIGUSR1 (black theme) or SIGUSR2 (white) to every foot window. This switches already open windows without restarting them. New windows start in the current theme via initial-color-theme.
foot 1.28 or newer is required: older versions do not know the [colors-dark] / [colors-light] sections.
SUPER+ALT+R starts recording, SUPER+ALT+S stops it. Recording uses wf-recorder (VAAPI H.264, 30 fps, audio from [record] audio) and falls back to libx264 when hardware encoding is unavailable. File: ~/Videos/review-*.mp4. Stopping waits until the file is finalized, so it opens immediately. The audio source is set by [record] audio: mic (default source), system (default sink monitor) or both (a temporary null sink mixing both). With mic, SUPER+ALT+M turns the microphone on (unmute at 100%) or off (mute) at any time, including during a recording. Start and stop are confirmed by a small square at the right edge above the center: filled means recording started, an outline means it stopped.
wf-recorder -f record.mp4 # whole screen, Ctrl+C to stopI record only the whole screen. Capturing individual windows requires foreign-toplevel, which vlswm does not implement. While recording vlswm disables direct scanout and composites every frame.
SUPER+SHIFT+A — select a region (slurp), save a PNG (grim) and copy it to the clipboard (wl-copy). File: ~/Downloads/YYYY-MM-DD-HHMMSS.png. Esc cancels.
vlswm is my notification daemon: it owns org.freedesktop.Notifications, so notifications from any app (Telegram, mail, scripts) appear on the left, vertically centered, as inverted-theme cards. Up to 3 cards are shown, each for 4 seconds. SUPER+N opens the panel with the last 50 notifications; Esc closes it, C clears the history. Recording start/stop and config reloads also post notifications.
Only one notification daemon can own the name: stop mako, dunst or another daemon if one is running.
SUPER+L locks the session. The lock screen reuses the QML from my SDDM theme (/usr/share/sddm/themes/vlswm); if the theme is not installed, it uses the embedded copy in /usr/share/vlswm/lock. The password is checked through PAM (/etc/pam.d/vlswm-lock), exactly like SDDM; if that file is missing, it falls back to system-auth. T / Ctrl+T toggle the palette, Ctrl+Shift+P/R/S power off, reboot or suspend. While the screen is locked, VLSWM keybindings are disabled and all windows are hidden.
SUPER+TAB opens my window switcher: a vertical panel in the center with the titles of the open windows, the current one highlighted, the topmost window first. ↑ / ↓ move the selection, Enter raises and focuses that window, Esc closes the panel without changing anything. Dialogs are not listed, so the switcher only shows real windows. While the panel is open, my other keybindings are disabled.
GTK apps (Zen, LocalSend, …) open their file dialogs through xdg-desktop-portal: vlswm sets GTK_USE_PORTAL=1 and exports the session environment, so the dialog runs outside the app. The FileChooser portal is routed to xdg-desktop-portal-termfilechooser, which opens yazi in a foot window. Enter confirms, Esc cancels; the selected path is written back to the app. Saving uses a short path prompt in the terminal.
install.sh installs ~/.config/xdg-desktop-portal/portals.conf, the termfilechooser config and yazi-wrapper.sh. The backend itself is in the AUR; without it the portal falls back to the GTK dialog. After changing the wrapper, restart the portal:
systemctl --user restart xdg-desktop-portal-termfilechooser xdg-desktop-portalSUPER+SHIFT+V opens a vertical panel in the center: typing filters entries, ↑/↓ selects, Enter puts the entry into the clipboard, Esc closes. History is kept by cliphist.
At session start vlswm runs wl-paste --watch cliphist store, so copying in any app lands in the history. cliphist and wl-clipboard are required.
vlswmstat is my compact monochrome dashboard: hostname, distro, kernel, system age, uptime, shell, terminal, CPU, memory, disks, network, sensors, battery and VLSWM data. The large clock and date update every second. System age comes from the root filesystem birth time; if the filesystem does not support it, the first line of /var/log/pacman.log is used.
vlswmstat # live dashboard, quit with q or Esc
vlswmstat --once # one frame and exit
vlswmstat --versionKeys: q / Esc — quit, r — refresh, window resizes are picked up automatically.
install.sh adds ~/.config/fish/conf.d/vlswmstat.fish, so the dashboard is shown as a greeting when the base terminal starts. New terminals (SUPER+ENTER) have no greeting. To disable it, comment out the vlswmstat line in that file.
| Keys | Action |
|---|---|
SUPER+D |
launcher |
SUPER+TAB |
window switcher |
SUPER+L |
lock the session |
SUPER+ENTER |
new terminal |
SUPER+Q |
close the focused window |
SUPER+← / SUPER+→ |
cycle windows |
SUPER+T |
black / white theme |
SUPER+SPACE |
switch layout (us / ru) |
SUPER+E |
file manager (yazi in a separate foot window) |
SUPER+Z |
zen-browser |
SUPER+ALT+R |
start screen recording |
SUPER+ALT+S |
stop screen recording |
SUPER+ALT+M |
microphone on / off |
SUPER+SHIFT+A |
screenshot of a selected region |
SUPER+SHIFT+V |
clipboard history |
SUPER+N |
notifications panel |
SUPER+SHIFT+R |
restart the base terminal (reset to fish) |
SUPER+R |
reload the config |
SUPER+ESC |
exit |
SUPER+F1 / SUPER+F2 |
brightness −/+ |
SUPER+F3 / SUPER+F4 |
volume −/+ |
src/main.cpp— startup, log, arguments.src/server.cpp— input, bindings, window stack, processes, xwayland-satellite.src/view.cpp— windows (xdg), open and close.src/launcher.cpp— launcher (cairo + pango).src/osd.cpp— volume and brightness overlay.src/clipboard.cpp— clipboard history picker.src/switcher.cpp— window switcher.src/notify.cpp— notification daemon, cards and panel.src/rec.cpp— recording start/stop indicator.src/overlay.cpp— shared buffer for the launcher, OSD and picker.src/theme.cpp— foot theme.src/vlswmstat.cpp— thevlswmstatdashboard.src/output.cpp,src/ini.cpp,src/animation.cpp— output, config, animations.scripts/vlswm-record— screen recording via wf-recorder.scripts/vlswm-screenshot— region selection and screenshot.scripts/vlswm-mic— microphone toggle for recording.scripts/vlswm-config-merge— appends new config options during an update.scripts/vlswm-env-install— installs environment.d, fish and portal configs.scripts/vlswm-smoke-test— headless startup and frame test.lock/—vlswm-lock(Qt6 Quick) and the lock screen QML.vlswm-update— installs the latest release.release.sh— cuts a release from a notes file.dots/— my personal Neovim, btop and cava configs and the theme watcher.
On my laptop TLP sets CPU_SCALING_GOVERNOR_ON_BAT=powersave on battery. With the intel_cpufreq driver (intel_pstate in passive mode, as on older Intel CPUs) that governor keeps the minimum frequency even under full load: 800 MHz instead of 2.9 GHz turbo. The whole system becomes 3–4 times slower and apps take much longer to start.
For my interactive work I need schedutil and turbo enabled. In /etc/tlp.conf I set:
CPU_SCALING_GOVERNOR_ON_BAT=schedutil
CPU_BOOST_ON_BAT=1TLP reads /etc/tlp.conf last, so values in /etc/tlp.d/*.conf will not override these lines. I apply it with sudo tlp start. At idle schedutil still drops to the minimum frequency, so idle power draw does not grow.
See the LICENSE file.











