🌊 sway-setup

A minimal but functional Sway rice script for Debian-based systems.
Installs all core packages, window manager configs, and themes — ready to go out of the box.

Part of the JustAGuy Linux window manager collection — installable standalone or via butterknife, the installer for Butterbian.

📖 Deep dive: the wiki. New to sway? Start with Architecture. NVIDIA users: read NVIDIA first. Pages exist for install, keybinds, theming, customization, and troubleshooting.

---

🚀 Installation

Quick Install

git clone https://justaguy.dev/drew/sway-setup.git
cd sway-setup
chmod +x install.sh
./install.sh

⚠️ NVIDIA users: Wayland on proprietary NVIDIA drivers needs extra setup. The installer runs nvidia-setup.sh automatically if a GPU is detected; it's also copied to ~/nvidia-setup.sh so you can re-run it. See the NVIDIA wiki page.

Installation Options

./install.sh [OPTIONS]

Options:
  --only-config      Only copy config files (skip packages and external tools)
  --help             Show help message

Full install steps, display-manager flow, and non-Debian notes live on the Install wiki page.

---

📦 What It Installs

Component	Purpose
sway	Tiling Wayland compositor / WM
swayidle	Idle daemon (dpms / lock triggers)
swaybg	Wallpaper
gtklock	Lock screen
waybar	Status bar
rofi	App launcher / cheatsheet / power menu
swaync	Notification daemon + center
foot, kitty	Terminals (foot lightweight, kitty main)
grim + slurp	Screenshot pair
cliphist + wl-clipboard	Clipboard history
xdg-desktop-portal-wlr	Wayland portals
thunar + plugins	File manager
firefox-esr	Default web browser
pipewire	Audio
nwg-look, nwg-displays	GTK / display configurators
kanshi, wlr-randr	Output management (kanshi opt-in)
autotiling	Optional auto layout switcher

💡 Themes by vinceliuice — Orchis (GTK) and Colloid (icons).

---

🤔 Why These Pieces?

The full rationale for each component (waybar vs. swaybar, rofi vs. wofi, gtklock vs. swaylock, etc.) lives in the wiki's Architecture page.

---

🎮 NVIDIA

Wayland on proprietary NVIDIA drivers needs three things: kernel modesetting, sway --unsupported-gpu, and (often) WLR_NO_HARDWARE_CURSORS=1. The installer runs nvidia-setup.sh automatically — full breakdown on the NVIDIA wiki page.

---

🔑 Keybindings Overview

Key Combo	Action
Super + Return	Launch terminal (kitty)
Super + Space	App launcher (rofi)
Super + Q	Close focused window
Super + /	Keybind cheatsheet
Super + B	Firefox
Super + Shift + B	Firefox (private)
Super + F	File manager (Thunar)
Super + E	Text editor (Geany)
Super + C / Super + Shift + C	Helium / Helium incognito
Super + G / Super + O / Super + D	GIMP / OBS / Discord
Super + Shift + T	Theme switcher (12 themes)
Super + Shift + R	Reload sway config
Super + Shift + Q	Exit sway
Super + X	Power menu (rofi)
Super + Shift + N	Toggle notification center (swaync)
Super + Shift + F	Toggle fullscreen
Super + Shift + Space	Toggle floating
Super + T / Super + W	Cycle layout / Tabbed layout
Alt + Tab / Alt + Shift + Tab	Cycle siblings / tabs
Super + H/J/K/L or Super + Arrows	Focus window
Super + Shift + H/J/K/L or Super + Shift + Arrows	Move window
Super + Ctrl + Arrows	Resize window
Super + Ctrl + =	Balance windows
Super + 1–9/0/-/=	Switch to workspace 1-12
Super + Shift + 1–9/0/-/=	Move window to workspace 1-12
Super + S / Super + Shift + S	Full / region screenshot

Full reference (media keys, screenshots, layouts, sway control) on the Keybinds wiki page.

Keybindings are configured via:

• ~/.config/sway/keybindings.conf
• ~/.config/sway/workspaces.conf
• ~/.config/sway/scripts/help (run manually or with Super + /)

On first login, a welcome notification points to ~/QUICKSTART-sway.md — a short cheat sheet you can delete when you're comfortable.

---

🎨 Theme Switcher

Super + Shift + T opens a rofi menu of 12 themes. Each theme swaps sway border colors, waybar palette, rofi palette, swaync palette, kitty color scheme, GTK theme + icons, and wallpaper — all in one shot. Takes about a second, no log out.

Shipped themes: Catppuccin, Doom One, Dracula, Everforest, GitHub Dark (default), Gruvbox, Kanagawa, Monokai, Moonfly, Nord, Retro, Rose Pine Moon.

See the Themes wiki page for how it works, how to add a theme, or how to extend what the switcher touches.

---

📂 Configuration Files

~/.config/sway/
├── config                # variables, output, input, appearance, includes
├── workspaces.conf       # workspace vars, switch/move bindings
├── rules.conf            # for_window rules, borders, gaps
├── keybindings.conf      # all bindsym lines
├── current-theme -> themes/<name>/   # symlink updated by thememenu
├── scripts/
│   ├── autostart.sh      # startup (swaync, waybar, lxpolkit, cliphist, portals)
│   ├── screenshot        # grim/slurp wrapper: full | region | copy
│   ├── changevolume      # volume + notifications
│   ├── thememenu         # theme switcher
│   ├── power             # rofi power menu
│   ├── help              # rofi keybind cheatsheet
│   └── sway-layout-menu.sh
├── waybar/               # config-glyphs + style-glyphs.css (style theme-managed)
├── rofi/                 # config/keybinds/power.rasi (all theme-managed)
├── swaync/               # config.json + style.css (style theme-managed)
├── gtklock/              # config.ini + style.css
├── foot/                 # foot.ini (color block theme-managed via include)
├── themes/
│   ├── _templates/       # waybar.css + rofi/*.rasi + swaync/style.css templates
│   └── <name>/           # per-theme colors.conf + foot-colors.ini + theme.conf
└── wallpaper/

---

🎨 Customization

Colors are handled by the theme switcher (Super + Shift + T). For layout, fonts, gaps, keybindings, output config, and other non-color tweaks, see the Customization wiki page — it walks through each config file with examples.

---

Credits

This project is a config on top of other people's software. Sway is by Drew DeVault and maintainers. Waybar by Alex Orzechowski. swaync by ErikReider. gtklock by jovanlanik. rofi-wayland by lbonn. foot by dnkl. kitty by Kovid Goyal. GTK + icon themes by vinceliuice — Orchis and Colloid.

---

License

GPL-2.0 - See LICENSE for details.

Support

Connect

• YouTube — tutorials and guides
• Butterforge — source code and projects
• The Butter Lab — Discourse forum
• The Churn — community chat (Fluxer)
• Wiki — documentation and guides
• Mastodon — @justaguylinux@fosstodon.org
• Butterbian — a Debian-based distro

---

Made with butter by JustAGuyLinux