Sway for beginners: My Wayland configuration explained

Sway arranges windows automatically and lets you control the desktop through a text file. My Sway configuration in the Cthulhu repository shows a practical setup with two monitors, a few workspaces and personal application shortcuts. We will read the important parts and try one small edit.

This tutorial assumes an already running Sway session. It explains the published file rather than installing an entire distribution. The repository also contains an older Arch copy; this guide follows WM/sway/config, reviewed on 7 October 2026.

Sway, Wayland and the rest of the desktop

Sway is a Wayland compositor with an i3-inspired workflow. It organises windows and display output. Terminals, launchers, status bars and audio tools are additional components. Tiling means that ordinary windows share the available area in an arrangement.

The configuration does not install those components. Alacritty, Rofi, Waybar, wpctl and playerctl must fit the actual setup. In particular, check whether your application launcher supports Wayland. For an introduction to my X11 approach, read the XMonad guide.

Reading variables and keybindings

The opening gives reusable values a name:

set $mod Mod4
set $term alacritty
set $menu rofi -show drun -show-icons

$mod selects Super, usually the Windows key. $term contains the terminal command and $menu the application launcher. You can therefore change an application in one place without rewriting every binding.

bindsym $mod+Return exec $term
bindsym $mod+d exec $menu
bindsym $mod+q kill
bindsym $mod+f fullscreen toggle
bindsym $mod+Shift+f floating toggle
bindsym $mod+Shift+c reload

bindsym connects a key combination to an action. exec starts a program; kill closes the focused window. Floating takes a window out of the tiled arrangement. These bindings come from my file and may differ from your distribution's defaults.

Mapping two monitors

My file places the main monitor on the left and the second to its right:

output DP-1 resolution 3440x1440@144.000Hz position 0,0 adaptive_sync off
output HDMI-A-1 resolution 1920x1080@60Hz position 3440,0 adaptive_sync off

The second X coordinate starts at 3440, the first screen's width in this setup. Output names, resolutions and refresh rates are personal hardware values. Adaptive Sync is disabled here; that is not a recommendation for every monitor.

Inside your running Sway session, first inspect your actual outputs and available modes:

swaymsg -t get_outputs

Compare the names and modes with your own hardware before adopting monitor settings. With scaling, also account for the logical arrangement. A laptop with one internal screen does not need my two-monitor block. Wallpaper paths under /home/nebu/... also need to become existing paths on your machine.

Assigning workspaces and moving windows

Workspaces are working areas. My file names two and assigns them to monitors:

set $ws1 "1"
set $ws2 "2"
workspace $ws1 output DP-1
workspace $ws2 output HDMI-A-1
bindsym $mod+1 workspace number $ws1
bindsym $mod+Shift+1 move container to workspace number $ws1

Super + 1 opens workspace 1. Super + Shift + 1 moves the focused window there. The corresponding bindings for workspace 2 are also present. An output assignment determines where that workspace should appear; it does not prescribe a destination for every application.

The published file has a compact personal set of bindings. Add focus and split shortcuts deliberately, using the standard Sway configuration as a reference. Replacing an existing file wholesale can otherwise remove keys you already rely on.

Window rules: app_id versus class

A dialog or virtual machine can be more comfortable as a floating window. My file includes these examples:

for_window [app_id="virt-manager"] floating enable, resize set 1000 700, move position center
for_window [class="Steam"] floating enable

app_id identifies native Wayland windows; class identifies X11 windows using XWayland. The appropriate value depends on the actual application and window. Inspect properties with:

swaymsg -t get_tree

Find the intended window and check its identifier. Title-based matches can catch too much; test a rule on a clearly identifiable window. My personal rules for games, video editors and emulators illustrate my needs, but do not guarantee universal fixes for those applications.

Startup commands, audio and the bar

exec starts a command at session startup. exec_always also runs it on reload. My file uses the latter for autotiling and a delayed Waybar restart. Reloading can therefore launch additional processes or rebuild the bar.

Volume keys call wpctl, while media keys use playerctl. The Print binding launches xfce4-screenshooter; its suitability needs checking in the particular Wayland environment. A binding alone does not establish that its helper is installed or works on every system.

An environment command also updates Wayland/desktop values for D-Bus-activated applications. The distribution supplies the precise portal setup. The Waybar tutorial explains the status bar using a separate test configuration.

Exercise: Change and validate window spacing

Use the configuration path actually loaded by your setup. This example assumes ~/.config/sway/config; older setups or explicit startup arguments can select another file. Make a backup:

cp -a --backup=numbered ~/.config/sway/config ~/.config/sway/config.before-tutorial

Change only the existing inner spacing, for example from 8 to 12:

gaps inner 12

Validate the edited file from your working session:

sway --validate --config ~/.config/sway/config

Correct any reported configuration errors before continuing. Validation does not verify hardware suitability or every external program. If the check succeeds, reload:

swaymsg reload

Open two tiled windows. The gap should change. Check Sway's response and any messages from startup helpers too. This exercise leaves your monitor and network settings in place.

Undo the edit and share diagnostics deliberately

Restore the previous gap value or copy back the saved file if that will not discard later changes:

cp -a ~/.config/sway/config.before-tutorial ~/.config/sway/config

Validate the restored file, then run swaymsg reload again. Editing and validation remain local. Window trees can contain document titles and application information, so review them before posting diagnostic output publicly. The same applies to personal paths in the configuration.

Configuration and official references

The source and command references were reviewed on 7 October 2026.

• My Sway configuration
• Sway configuration reference
• Sway IPC and swaymsg manual
• Sway manual: configuration paths and validation