# Moonswing – A Desktop Environment for Linux in Flutter

> Source: <https://github.com/miracle-wm-org/moonswing>
> Published: 2026-10-19 20:09:29+00:00

A largely AI-coded, very unserious, just for fun desktop

  environment for Linux, built entirely in Flutter.

[**Website & wiki**](https://miracle-wm-org.github.io/moonswing/) ·
  [Install](https://miracle-wm-org.github.io/moonswing/start/install/) ·
  [Configuration](https://miracle-wm-org.github.io/moonswing/configuration/)

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.

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.

- `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
```

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
flutter run
```

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

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

The site lives in [`website/`](https://github.com/miracle-wm-org/moonswing/blob/main/website) and is built with
[Astro](https://astro.build) and [Starlight](https://starlight.astro.build). 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`](https://github.com/miracle-wm-org/moonswing/blob/main/website/README.md).

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.