> For the complete documentation index, see [llms.txt](https://hacking-notes.jord4n.pro/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hacking-notes.jord4n.pro/useful-resources/gh0stzk-bspwm-dotfiles.md). # Arch Linux Hacker Setup With BSPWM Arch Linux hacker setup guide with gh0stzk BSPWM dotfiles, fast installation, themes, Polybar, Rofi, ZSH, Neovim, commands, and keyboard shortcuts. [gh0stzk/dotfiles](https://github.com/gh0stzk/dotfiles) is a complete BSPWM desktop environment for Arch Linux and Arch-based distributions. It includes themes, bars, launchers, terminal settings, ZSH, Neovim, Rofi applets, wallpapers, and helper scripts for switching styles quickly.
gh0stzk BSPWM dotfiles desktop screenshot with terminal and Linux fetch output

Example BSPWM desktop environment from the project README.

{% hint style="warning" %} Install this only on a personal lab machine or a fresh Linux workstation. Dotfiles replace many user configuration files, so review the installer and back up your current setup before running it. {% endhint %} ## Where It Fits This belongs in `Useful Resources` because it is a workstation setup resource, not a pentesting tool. Use it when you want a clean Arch-based BSPWM environment for daily notes, labs, CTF work, development, and terminal-heavy workflows. ## What It Gives You | Component | What it means | | ------------- | -------------------------------------------------------------------------------------------- | | BSPWM | Tiling window manager for a fast keyboard-driven desktop. | | 18 themes | Ready-made visual styles that can be switched on the fly. | | Polybar | Desktop bar with workspaces, modules, system info, and theme colors. | | Rofi applets | Menus for apps, power, screenshots, clipboard, network, Bluetooth, wallpapers, and more. | | Terminals | Theme support for Alacritty, Kitty, Ghostty, ST, and Xfce Terminal. | | ZSH config | Fast shell setup with completions, history search, and fzf-tab previews. | | Neovim config | Prebuilt editor setup with LSP, completion, formatting, explorer, statusline, and dashboard. | | RiceEditor | Helper app for adjusting visual settings without manually editing every config. | ## Visual Preview The project is very visual, so check the screenshots and demo before installing.
gh0stzk dotfiles theme selector screenshot

Theme selector.

gh0stzk dotfiles wallpaper selector screenshot

Wallpaper selector.

gh0stzk dotfiles RiceEditor screenshot

RiceEditor for theme customization.

### Project Demo {% embed url="" %} ### Arch Install Walkthrough This creator video is useful if you want a clean Arch install before applying the dotfiles. {% embed url="" %} ### Project Channel The author's channel contains more BSPWM, Polybar, Eww, Rofi, and theme demos. {% embed url="" %} ## Before Installing The official installer is intended for Arch Linux and Arch-based distributions. The README notes that non-systemd distributions such as Artix are not supported. Recommended starting point: | Requirement | Notes | | ------------------------- | ---------------------------------------------------- | | Arch or Arch-based distro | Fresh install is safest. | | Normal user account | Do not run the installer as root. | | Working internet | The installer downloads packages and repositories. | | Login manager | LightDM is recommended by the project. | | NetworkManager | Needed for the Rofi network applet. | | Backup | Keep a copy of existing `~/.config` and shell files. | Useful backup command before testing: ```bash mkdir -p "$HOME/dotfiles-backup" cp -a "$HOME/.config" "$HOME/dotfiles-backup/config-$(date +%F)" 2>/dev/null cp -a "$HOME/.zshrc" "$HOME/.gtkrc-2.0" "$HOME/.icons" "$HOME/dotfiles-backup/" 2>/dev/null ``` ## Fast Arch Setup Use this when you are starting from a clean Arch machine or VM and want the shortest practical path. ### 1. Boot Arch ISO Start from the official Arch ISO. If you use Wi-Fi, connect first: ```bash iwctl ``` Inside `iwctl`: ``` device list station wlan0 scan station wlan0 get-networks station wlan0 connect "SSID" exit ``` Check internet: ```bash ping -c 3 archlinux.org ``` Sync time: ```bash timedatectl set-ntp true ``` ### 2. Install Arch quickly The fast route is `archinstall`: ```bash archinstall ``` Recommended choices: | Option | Pick | | -------------- | ---------------------------------------------------------------------------- | | Disk layout | Default or manual, depending on your VM/disk. | | Bootloader | `systemd-boot` for UEFI, GRUB if you prefer it. | | Profile | Minimal is enough; desktop is optional. | | Network | NetworkManager. | | Audio | PipeWire. | | User | Create a normal user with sudo access. | | Extra packages | `git curl base-devel xorg-server lightdm lightdm-gtk-greeter networkmanager` | After install: ```bash reboot ``` ### 3. Enable the basics Log in as your normal user, then make sure the base services are ready: ```bash sudo pacman -Syu sudo pacman -S --needed git curl base-devel xorg-server lightdm lightdm-gtk-greeter networkmanager sudo systemctl enable --now NetworkManager sudo systemctl enable lightdm ``` Reboot once more if you just enabled LightDM: ```bash sudo reboot ``` ## Dotfiles Installation Open a terminal from your home directory: ```bash cd "$HOME" ``` Download the official installer: ```bash curl -LO http://gh0stzk.github.io/dotfiles/RiceInstaller ``` Review the installer before executing it: ```bash less RiceInstaller ``` Give it execution permission: ```bash chmod +x RiceInstaller ``` Run it as your normal user: ```bash ./RiceInstaller ``` The installer is interactive. It may ask whether you want the included Neovim and Firefox configurations. Read each prompt instead of pressing enter through everything. ### One Block Install For a quick lab install after you already have working Arch: ```bash cd "$HOME" curl -LO http://gh0stzk.github.io/dotfiles/RiceInstaller less RiceInstaller chmod +x RiceInstaller ./RiceInstaller ``` ## What The Installer Does At a high level, the installer: 1. Checks that it is not being run as root. 2. Checks that it is being executed from `$HOME`. 3. Adds the `gh0stzk-dotfiles` package repository. 4. Adds Chaotic-AUR. 5. Downloads the dotfiles. 6. Backs up existing user configs where needed. 7. Installs the BSPWM environment. 8. Enables MPD for music features. 9. Changes the shell to ZSH. The script also moves many existing config folders into a backup directory before replacing them. Still, keep your own backup first. ## First Login After installation: 1. Reboot or log out. 2. Select the BSPWM session from your login manager. 3. Log in normally. 4. Wait for the first launch to finish autoconfiguration. 5. Test terminal, Rofi, Polybar, theme selector, and wallpaper selector. If you are in a virtual machine and the desktop feels broken or slow, try changing Picom from `glx` to `xrender` before assuming the installation failed. ## First Things To Check After the first launch, verify the hardware-related variables. Open: ```bash ~/.config/bspwm/config/system.ini ``` Check values for: | Value | Why it matters | | ------------------- | -------------------------------------- | | Network interface | Network modules in the bar. | | Graphics card | Some visual and status modules. | | Battery and adapter | Laptop battery and brightness modules. | If you are on a desktop PC, the network interface is usually the main one to care about. ## Useful Commands | Command | Use | | ----------------------------------- | -------------------------------------------------- | | `RiceSelector` | Open the theme selector. | | `RiceEditor` | Edit the current theme visually. | | `WallSelect` | Open wallpaper selector. | | `Term --selecterm` | Choose the terminal app. | | `OpenApps --menu` | Open app launcher. | | `OpenApps --KeyHelp` | Open the keybinding cheatsheet. | | `OpenApps --screenshot` | Open screenshot tool. | | `OpenApps --netmanager` | Open network manager applet. | | `OpenApps --bluetooth` | Open Bluetooth applet. | | `OpenApps --clipboard` | Open clipboard manager. | | `OpenApps --powermenu` | Open power menu. | | `OpenApps --keyboard` | Open keyboard layout applet. | | `OpenApps --scratch` | Open scratchpad. | | `HideBar -h` | Hide bars. | | `HideBar -u` | Show bars. | | `SoftReload` | Soft reload the environment. | | `ScreenLocker` | Lock the screen. | | `bspc wm -r` | Reload BSPWM. | | `pkill -USR1 -x sxhkd` | Reload keybindings. | | `~/.config/bspwm/config/system.ini` | Hardware/module variables to verify after install. | | `~/.config/bspwm/config/sxhkdrc` | Main keybinding file. | ## Complete Keybindings The project shows the visual cheatsheet with `Alt + F1`. `Super` means the Windows key on most keyboards. The source of truth is the installed `~/.config/bspwm/config/sxhkdrc`; this table follows the current upstream file and groups every shortcut so it is easier to scan. ### Help | Keys | Action | | ---------- | --------------------------- | | `Alt + F1` | Show keybinding cheatsheet. | ### Main Apps | Keys | Action | | ---------------------- | -------------------------- | | `Super + Return` | Open normal terminal. | | `Super + Alt + Return` | Open floating terminal. | | `Super + Space` | Open app launcher. | | `Alt + Space` | Open theme selector. | | `Super + B` | Open browser. | | `Super + E` | Open editor. | | `Super + F` | Open file manager. | | `Super + Y` | Open Yazi. | | `Super + V` | Open Neovim. | | `Super + M` | Open music player/Ncmpcpp. | | `Super + P` | Open Pavucontrol. | | `Super + T` | Open Telegram. | | `Super + W` | Open WhatsApp. | | `Super + R` | Open RiceEditor. | ### Rofi Applets | Keys | Action | | ------------------------ | ----------------------------- | | `Super + Alt + T` | Terminal selector. | | `Super + Alt + W` | Wallpaper selector. | | `Super + Alt + A` | Android mount applet. | | `Super + Alt + N` | Network manager. | | `Super + Alt + B` | Bluetooth manager. | | `Super + Alt + C` | Clipboard manager. | | `Super + Alt + S` | Screenshot tool. | | `Super + Alt + P` | Power menu. | | `Super + Alt + L` | Rofi launcher style selector. | | `Super + Alt + K` | Keyboard layout applet. | | `Super + Alt + X` | RofiPass/password applet. | | `Right click on desktop` | Open Jgmenu. | ### System And Environment | Keys | Action | | ------------------------ | ---------------------------------------- | | `Super + Alt + O` | Scratchpad. | | `Ctrl + Super + Alt + P` | Power off computer. | | `Ctrl + Super + Alt + R` | Reboot computer. | | `Ctrl + Super + Alt + Q` | Log out. | | `Ctrl + Super + Alt + L` | Lock screen. | | `Ctrl + Super + Alt + K` | Kill app with `xkill`. | | `Ctrl + Super + Alt + S` | Soft reload. | | `Super + Alt + H` | Hide bar. | | `Super + Alt + U` | Show bar. | | `Ctrl + Alt + Plus` | Increase transparency on focused window. | | `Ctrl + Alt + Minus` | Decrease transparency on focused window. | | `Ctrl + Alt + T` | Reset transparency on focused window. | | `XF86MonBrightnessUp` | Increase brightness. | | `XF86MonBrightnessDown` | Decrease brightness. | | `XF86AudioRaiseVolume` | Increase volume. | | `XF86AudioLowerVolume` | Decrease volume. | | `XF86AudioMute` | Toggle mute. | | `XF86AudioNext` | Next media track. | | `XF86AudioPrev` | Previous media track. | | `XF86AudioPlay` | Play/pause media. | | `XF86AudioStop` | Stop media. | ### BSPWM Core | Keys | Action | | ------------------- | ------------------------- | | `Super + Alt + R` | Reload BSPWM. | | `Super + X` | Close focused node. | | `Super + Shift + X` | Kill focused node. | | `Super + Escape` | Reload sxhkd keybindings. | ### Node States And Flags | Keys | Action | | ----------------- | ------------------------------------ | | `Alt + T` | Set node tiled. | | `Alt + Shift + T` | Set node pseudo tiled. | | `Alt + A` | Set node floating. | | `Alt + F` | Set node fullscreen. | | `Alt + M` | Toggle marked flag. | | `Alt + X` | Toggle locked flag. | | `Alt + S` | Toggle sticky flag. | | `Alt + P` | Toggle private flag. | | `Alt + H` | Hide focused window. | | `Ctrl + Alt + H` | Show menu to restore hidden windows. | ### Workspaces And Focus | Keys | Action | | ---------------------------------------- | ----------------------------------------------------- | | `Ctrl + Tab` | Rotate desktop. | | `Super + Left` | Switch to previous workspace. | | `Super + Right` | Switch to next workspace. | | `Super + 1` to `Super + 9` | Focus workspace 1 to 9. | | `Super + 0` | Focus workspace 10. | | `Super + Ctrl + 1` to `Super + Ctrl + 9` | Send focused window to workspace 1 to 9. | | `Super + Ctrl + 0` | Send focused window to workspace 10. | | `Super + Ctrl + Left` | Send focused window to previous workspace and follow. | | `Super + Ctrl + Right` | Send focused window to next workspace and follow. | | `Alt + Tab` | Window switcher. | | `Super + Alt + Left` | Focus window to the west, fallback previous. | | `Super + Alt + Down` | Focus window to the south. | | `Super + Alt + Up` | Focus window to the north. | | `Super + Alt + Right` | Focus window to the east, fallback next. | | `Ctrl + Alt + Left` | Swap focused window west. | | `Ctrl + Alt + Down` | Swap focused window south. | | `Ctrl + Alt + Up` | Swap focused window north. | | `Ctrl + Alt + Right` | Swap focused window east. | | `Ctrl + Shift + Comma` | Focus last node. | | `Ctrl + Shift + Period` | Focus last desktop. | ### Preselection | Keys | Action | | ------------------ | -------------------------------- | | `Super + Ctrl + H` | Preselect horizontal/east split. | | `Super + Ctrl + V` | Preselect vertical/south split. | | `Super + Ctrl + Q` | Cancel preselection. | ### Move And Resize | Keys | Action | | ----------------------- | ---------------------------- | | `Super + Ctrl + B` | Balance desktop nodes. | | `Super + Alt + Plus` | Increase tiled node size. | | `Super + Alt + Minus` | Decrease tiled node size. | | `Super + Ctrl + Plus` | Increase floating node size. | | `Super + Ctrl + Minus` | Decrease floating node size. | | `Super + Shift + Left` | Move floating window left. | | `Super + Shift + Down` | Move floating window down. | | `Super + Shift + Up` | Move floating window up. | | `Super + Shift + Right` | Move floating window right. | ### Multi Operation | Keys | Action | | ---------------------------- | ------------------------------------------------------------ | | `Super + Ctrl + X` | Close all nodes in current desktop. | | `Super + N`, then `X` | Close all unfocused local windows. | | `Super + N`, then `K` | Kill all unfocused local windows. | | `Super + N`, then `M` | Bring all marked windows to focused desktop. | | `Super + N`, then `1` to `9` | Bring every window from that desktop to the current desktop. | ## Common Customization ### Change Theme Use: ``` Alt + Space ``` Pick a theme from the selector. The environment updates without needing to restart the full session. ### Change Wallpaper Use: ``` Super + Alt + W ``` The project supports random wallpapers, custom directories, fixed wallpapers, animated wallpapers, and slideshow behavior. ### Edit Current Theme Use RiceEditor when you want to adjust visual settings without manually editing every module: ``` RiceEditor ``` Typical edits include borders, shadows, animations, transparency, wallpaper behavior, and theme-specific module settings. ## Troubleshooting | Problem | What to check | | -------------------------------- | -------------------------------------------------------------------------------- | | Login returns to display manager | Confirm BSPWM session is installed and review `~/.xsession-errors`. | | Bar modules are wrong | Check `~/.config/bspwm/config/system.ini`. | | Network applet does not work | Confirm NetworkManager is installed and running. | | VM graphics look broken | Try Picom `xrender` backend instead of `glx`. | | Keyboard shortcuts fail | Check `sxhkd` is running and review `~/.config/bspwm/config/sxhkdrc`. | | Theme looks misaligned | The project is designed around 1600x900 and 96 DPI; adjust for your monitor. | | Existing configs disappeared | Check the backup folder created by the installer and your own `dotfiles-backup`. | ## Clean Reinstall Notes For the safest retry: 1. Back up your current files. 2. Remove or move old dotfiles directories. 3. Re-download the latest `RiceInstaller`. 4. Review the script again. 5. Run it from `$HOME` as a normal user. Do not run random modified installers from third-party forks unless you have reviewed the diff. ## References * [gh0stzk/dotfiles official repository](https://github.com/gh0stzk/dotfiles) * [RiceInstaller](https://github.com/gh0stzk/dotfiles/blob/master/RiceInstaller) * [First steps after installation](https://github.com/gh0stzk/dotfiles/wiki/First-steps-after-installation) * [Keyboard shortcuts wiki](https://github.com/gh0stzk/dotfiles/wiki/Keyboard-Shortcuts) * [Current sxhkdrc keybinding file](https://github.com/gh0stzk/dotfiles/blob/master/config/bspwm/config/sxhkdrc) * [Wallpapers configuration wiki](https://github.com/gh0stzk/dotfiles/wiki/Wallpapers-Configuration) * [ArchWiki: bspwm](https://wiki.archlinux.org/title/Bspwm) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://hacking-notes.jord4n.pro/useful-resources/gh0stzk-bspwm-dotfiles.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.