Moonswing

The purpose of this project is to:

1. Stress test Flutter
2. Explore the bounds of building new desktops for Wayland
3. Experiment with new Wayland protocols, portals, and everything else
4. Have fun

Use this project at your own risk!

This project may be entirely unstable. The snap will be the only supported packaging from my end. The config format is subject to change at any time.

Install

To get the latest nightly snap (amd64):

curl -fsSL https://raw.githubusercontent.com/miracle-wm-org/moonswing/main/install.sh | sh

Then, in your environment of choice (miracle-wm, Miriway, Sway, etc.), run:

moonswing

To have miracle-wm start Moonswing with every session, add --miracle-autostart:

curl -fsSL https://raw.githubusercontent.com/miracle-wm-org/moonswing/main/install.sh | sh -s -- --miracle-autostart

This adds Moonswing to the startup_apps of ~/.config/miracle-wm/config.yaml, restarted whenever it exits and run in its own systemd scope:

startup_apps:
  - command: /snap/bin/moonswing
    restart_on_death: true
    in_systemd_scope: true

An existing config is kept and the entry added to it (the original is saved alongside as config.yaml.<timestamp>.bak); with no config, one is created holding just this. If Moonswing is already a startup app there, the file is left untouched.

Re-run the same command to update, and to remove:

sudo snap remove moonswing

FYI! The snap cannot install the PAM service file for you.

• The PAM service file. /etc/pam.d/moonswing needs root, so the lock screen falls back to the system login service — it still authenticates, it just attributes unlock attempts to login in the auth logs.

Building Locally

Dependencies

• libgtk3
• gtk-layer-shell
• libasound2-dev
• libmpv-dev

On Ubuntu 26.04:

sudo apt install libgtk-3-dev libgtk-layer-shell-dev libasound2-dev libmpv-dev

You will also need Flutter:

sudo snap install flutter --classic
flutter channel master
flutter upgrade
flutter config --enable-windowing

Some dependencies are needed for the runtime to work properly, but they are not necessary if you plan to to not use these features:

sudo apt install libgtk-session-lock0  # Lock screen

Building

Build and install to ~/.local (default), or to a custom prefix:

make install
make install PREFIX=/usr/local

Then run:

moonswing

Optionally, install the lock screen's PAM service file (needs root, and writes to /etc/pam.d rather than the prefix):

sudo make install-pam

Without it the lock screen falls back to the system login service, which works but attributes unlock attempts to login in the auth logs.

To uninstall:

make uninstall
sudo make uninstall-pam   # if you installed the PAM service file

Running in development

flutter run

Documentation

The docs are very AI generated, and probably somewhat useless.

The full configuration reference is in CONFIG.md, and the same content — plus install, build and wiki pages — is published at https://miracle-wm-org.github.io/moonswing/.

The site lives in website/ and is built with Astro and Starlight. To run it locally:

cd website
npm install
npm run dev          # http://localhost:4321/moonswing/

Its configuration pages are generated from CONFIG.md and its artwork from assets/, so neither is maintained twice. See website/README.md.

Contributing

Bug reports and feature requests are very welcome. Please make an issue on the Github project to suggest one.

Because of how AI-coded this project is, I am not accepting pull requests on it, unless they are for very minor bug fixes. I cannot feasibly read large pull requests and feel satisfied that they are not malicious. As a result, any large pull request that includes a full feature will be closed.