# swaystation: a Sway workstation dotfile set for Arch Linux

> swaystation is a dotfile collection for an Arch Linux and Sway workstation, pairing a specific set of applications, from waybar and Rofi to foot and Neovim, with an installer that keeps every config file in one directory and symlinks it into place. The README is candid that you must edit the hardware settings and the package lists before running it.

**mister-grimm96/swaystation** — A collection of dotfiles based on arch linux and swaywm

- Repository: https://github.com/mister-grimm96/swaystation
- Stars: 790 · Forks: 30
- Language: Lua
- License: not declared
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/mister-grimm96-swaystation

## The stack this configuration assumes

The README opens with a list of what the configuration is built around, and it is a specific stack rather than a philosophy.

The operating system is Arch Linux and the window manager is Sway, so this is a Wayland compositor setup with the topics confirming wayland and wayland-compositor. The bar is waybar, the launcher is Rofi, and the terminal is foot. The file managers are Pcmanfm for the desktop and lf for the terminal, and the media players are cmus for music and mpv for video. The primary browser is firefox-developer-edition, the code editor is Neovim, and the lockscreen is swaylock. Screenshots are taken with Grim and Satty, the policykit agent is mate-polkit, the shell is bash, and the wallpaper utility is swaybg.

The fonts are listed with some care, which is typical of a configuration where the terminal and the bar are the main surfaces: iosevkaterm nerd font, roboto-condensed and jetbrainsmono nerd font.

The primary language of the repository is Lua, which is worth noting because the applications listed are not Lua ones. Sway's own configuration language is a C-like dialect, not Lua, and Neovim's configuration is Lua, so the Lua tag almost certainly reflects the Neovim configuration rather than the desktop as a whole. That tells you something about where the author's own work is.

The licence field on the repository carries no identifier, and the last push was on 2026-10-11.

## Installing with the three-line script

The installation is a shell block that clones the repository and runs the installer.

```sh
mkdir -p "$HOME/workstationdots"
[ -d "$HOME/workstationdots/swaystation" ] || git clone -b main https://github.com/mister-grimm96/swaystation "$HOME/workstationdots/swaystation" --depth=1
bash "$HOME/workstationdots/swaystation/install_scripts/install.sh"
```

The shape of that is deliberate. The directory is created if it does not exist, the clone is guarded by a test so that re-running the block does not fail on an existing directory, and the clone uses the main branch with a shallow depth.

The README explains the two cases around it. If the base Arch Linux install is already done, you clone the repository into the workstationdots directory, creating it if it does not exist, and then run install.sh.

Two things to understand before running it, both flagged in the important callout. Save all of your wallpapers in the $HOME/Pictures/backgrounds directory, because the wallpaper scripts are designed that way. And do not forget to change the settings related to your hardware in config/sway/devices.conf, which is the file that tells Sway about your displays and inputs.

The README also asks you to check the variables.conf file of each window manager config directory at the beginning, and to store your bookmarks as .txt files in the bookmarks directory under the config_dotfiles path, because the bookmark scripts read them from there.

## How the symlink-based install works

The installer has a small design, and the README explains the reasoning in detail.

All the dotfiles are stored in a folder called config_dotfiles inside the $HOME/.local/share directory. If a config already exists in the $HOME/.config directory, it is backed up into $HOME/.config.backup with a timestamp in the name formatted as year, month, day, underscore, then hours, minutes and seconds. Then a symlink is created from the $HOME/.local/share/config_dotfiles directory to the respective directories.

The README gives the reason for that approach rather than creating real directories: it is easy to dump them all together in the project folder after making huge changes in multiple application configs. That is the argument, and it is a real one. If every application config were a physical file in $HOME/.config, tracking the state of your desktop across a dozen applications means a dozen diffs in a dozen places. If every config is a symlink into one directory, the whole desktop configuration is one tree you can commit, diff and revert.

The mechanism for the symlinking is a database file. The details of the configs must be mentioned in the config_dotfiles.db.json file for the symlinking process, so the mapping from a config file to its destination is data rather than a hardcoded list in the script.

That design has a consequence worth stating: the repository is not just a set of files, it is a set of files plus an install script plus a mapping file, and all three have to be kept consistent for a clean install.

## The install script layout and the package lists

The README shows the installer as a directory tree, which makes the structure of the whole thing clear.

```sh
.
├── db
│   └── config_dotfiles.db.json
├── install.sh
├── package_lists
│   ├── cmus_pkg_list.txt
│   ├── common_pkg_list.txt
│   ├── dev_pkg_list.txt
│   ├── flatpak_pkg_list.txt
│   ├── gui_pkg_list.txt
│   └── wayland_pkg_list.txt
└── scripts
    ├── copy_from_src_to_des.sh
    ├── enable_services.sh
    ├── install_aur_helper.sh
    ├── install_with_flatpak.sh
    ├── install_with_pacman.sh
    ├── make_directories.sh
    ├── mini_functions.sh
    └── symlink_configs.sh
```

The scripts directory is the actual work, and each script is named for what it does: make_directories.sh creates the directories, install_with_pacman.sh installs the system packages, install_with_flatpak.sh handles the Flatpak applications, install_aur_helper.sh sets up an AUR helper, symlink_configs.sh does the linking, copy_from_src_to_des.sh copies things from the source to the destination, enable_services.sh enables the services, and mini_functions.sh holds the shared helpers.

The package lists are separated by category, which is the part you are expected to edit. The caution callout says you can check the list of packages in the package_lists directory before installing and modify it according to your liking, and if you add a new package list file you must also modify the install_with_pacman script. The README shows exactly how, with a mapfile command that reads the list into an array.

```sh
mapfile -t [variable_name] < "$INSTALL_WITH_PACMAN_SCRIPT_PATH/../package_lists/[name_of_your_pkg_list_file].txt"
```

And then a call to run_function install_with_pacman with that array. The flatpak script is optional and has to be run manually after you add your preferred applications, which is a sensible arrangement since the Flatpak list is the one most likely to be personal.

## Workspaces, keymaps and the Neovim configuration

The configuration details in the README are where the personal nature of the project shows.

The workspace layout is a table of ten numbered workspaces with an assigned purpose: terminal, browser, development and coding, file manager, chat, design tools, office tools, video projects, games, and system tools and miscellaneous. It is a deliberate single-purpose-per-workspace layout, which is the classic Sway arrangement and the reason a tiling compositor with workspaces exists at all.

The keymaps are not in the README but are pointed at, in the swaywm keymaps file under the config directory, and the same directory has a variables file that the README asks you to check at the beginning.

The waybar themes are switchable, and the way to reach the theme selector is mod+shift+s and then b.

The Neovim section is the longest part of the README and it is a personal configuration rather than a distribution, as the author says. It comes with a start page, a file tree from mini.files, a fuzzy finder from Snacks.nvim, LSP and autocompletion support, the gitsigns plugin for a visual git status, and Lazy as the plugin manager with Mason as the LSP manager.

The install instruction for it is a caution worth repeating, because the failure mode is a broken editor. Remove or back up the nvim folder from four separate locations, which are the config, the cache, the local share and the local state directories, and then copy the nvim config folder into the ~/.config directory. Four directories rather than one is because Neovim keeps state in all of them, and a partial cleanup leaves old plugins and old plugin manager state behind.

## Where swaystation is the wrong choice

The first limitation is that it is for Arch Linux specifically, and the package installation step is a pacman step. The install script is written around the Arch package manager, and the repository carries an install_aur_helper.sh script, so the whole design assumes an Arch system with an AUR helper. On another distribution you would be rewriting the package step rather than adjusting it.

The second is the hardware configuration. The README explicitly says to change the settings related to your hardware in the sway/devices.conf file, which means the display and input configuration is specific to the machine it was written on and has to be adapted. A dotfile set cannot know your monitor names, your scaling or your keyboard.

The third is the amount of opinion. This is a complete desktop with a bar, a launcher, a theme selector, ten workspaces with fixed purposes, a browser choice, a terminal, two file managers and a personal Neovim configuration. That is a coherent set of choices, but it is one person's set, and the question of whether a dotfile set is worth adopting is really a question of whether you want their desktop or your own.

The fourth is the install script's blast radius. It creates directories in your local share, backs up your existing configuration, symlinks a tree into your .config directory and installs system packages. The backup step is a genuine safeguard, but a script that reorganises your home directory should be read line by line rather than run on trust, and this one is a shell script with no integrity check.

The fifth is the missing licence. The repository records no licence identifier, and the README does not discuss licensing. Without one, the default copyright rules apply, so you can read the configuration and take the ideas, but you have no clear permission to redistribute the files as a dotfile set of your own.

## How swaystation compares with a Sway install script and with stow

The comparison with the official Sway installation is the first one, and the difference in approach is that the official path gives you a minimal, correct configuration you then adjust, while this gives you a finished one you then adjust. The official installation is a small set of files and a package list; a user who wants Sway with a bar and a launcher builds that from the Sway wiki recipes. The result is a configuration that is minimal and that the user understands completely, because they assembled it.

The comparison with GNU Stow is the closest in mechanism, and it is worth being precise about the difference. Stow manages symlinks from a package directory into a target directory, and it does it in a general, tool-agnostic way with its own conflict resolution. This installer does the same thing with a mapping database, but the mapping is specific to this configuration, the destination layout is dictated by what the applications expect, and the symlink targets are the .config directories themselves rather than per-file entries. So the two share the idea and differ in the generality.

The third comparison is with the AUR and with a package manager for dotfiles. A dotfile manager is a tool for tracking your own configuration across machines, and the interesting part of that is the version history. This repository is a single published configuration, and the version history that matters is the git history of the repository itself, which works if you clone it and keep the remote.

The fourth is the simplest option. A Sway user who writes their own config file, or copies two or three files from the wiki, ends up with something they fully own. The cost of a complete dotfile set is that you are then maintaining someone else's decisions, and every upstream change arrives as a conflict in your own tree.

## Maintenance state and what to check before you run the installer

The repository is not archived and the last push was on 2026-10-11, so the configuration is being worked on. There are no GitHub releases, so the commit history is the only version record, and the repository has just two top level entries, the README and the two directories that hold everything, config_dotfiles/ and install_scripts/.

The images in the README are hosted in a separate repository, swaystation-misc, which holds the screenshots and the gallery animations. That is a common arrangement for a dotfile repository, since binaries and screenshots make a repository large, and it means the gallery is not versioned alongside the configuration it shows.

Four things to check before you run install.sh.

That you are on Arch Linux, and that you have pacman and an AUR helper, since the package step assumes both.

That you have read the install script. It creates directories under your local share, moves your existing .config contents into a timestamped backup, creates symlinks and installs packages, and you should know that before running it.

That you have edited config/sway/devices.conf for your hardware, and that you have looked at the variables.conf file in each window manager config directory, since the README asks for both explicitly.

And that you have edited the package lists in install_scripts/package_lists, since installing every package by default will pull in applications you may not want, and the README's own advice is to trim the lists before installing.

## Conclusion

swaystation suits someone setting up an Arch and Sway machine who wants a complete, coherent configuration rather than assembling a desktop piece by piece, and who is comfortable reading a shell installer before running it. It is the wrong choice for a machine that is not Arch, for a user who wants a keyboard-driven setup they can build themselves, and the wrong choice if you want a configuration that survives a distribution change. Before running the installer, read the package lists in install_scripts/package_lists and edit the hardware settings in config/sway/devices.conf, because the README marks both as things you must change first.

## FAQ

### What is swaystation?

It is a collection of dotfiles for an Arch Linux workstation running Sway, with waybar, Rofi, foot, Pcmanfm, lf, cmus, mpv, Neovim, swaylock, Grim with Satty, mate-polkit, swaybg and a set of fonts. The repository contains the configuration and the install scripts.

### How do I install swaystation?

Create $HOME/workstationdots, clone the main branch with git clone -b main into $HOME/workstationdots/swaystation with a depth of 1, then run bash on the install_scripts/install.sh script inside the clone. The clone is guarded so re-running it does not fail on an existing directory.

### How does the swaystation installer handle my existing configuration?

All dotfiles are stored under a config_dotfiles folder in $HOME/.local/share. If a config already exists in $HOME/.config it is backed up into $HOME/.config.backup with a timestamp formatted as %Y%m%d_%H-%M-%S, and then a symlink is created from the config_dotfiles directory to the respective directories, with the mapping held in the config_dotfiles.db.json file.

### Can I change which packages the swaystation installer installs?

Yes. The package lists live in install_scripts/package_lists as per-category text files, and the README says to check and modify them before installing. If you add a new list file you must also add a mapfile line and a call to run_function install_with_pacman in the install_with_pacman script. The flatpak script is optional and run manually.

### What must I change before installing swaystation?

The README asks you to save your wallpapers in $HOME/Pictures/backgrounds because the wallpaper scripts expect them there, to change the hardware settings in config/sway/devices.conf, and to check the variables.conf file in each window manager config directory. Bookmarks go in .txt files under the bookmarks directory so the bookmark scripts can read them.

### What workspaces does the swaystation Sway configuration use?

Ten numbered workspaces, each with an assigned purpose: terminal, browser, development and coding, file manager, chat, design tools, office tools, video projects, games, and system tools and miscellaneous. The keymaps are in the swaywm keymaps file under the configuration directory.

## Sources

- [Issues](https://github.com/mister-grimm96/swaystation/issues)
- [mister-grimm96/swaystation on GitHub](https://github.com/mister-grimm96/swaystation)
- [README](https://github.com/mister-grimm96/swaystation/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mister-grimm96-swaystation