feat(release): publish an AppImage for each Linux architecture

- Releases now include Midi-Harbor-<version>-<x86_64|aarch64>.AppImage, built from the same binary as the packages and listed in checksums.txt, for distributions without a .deb or .rpm. Opened with no arguments it shows the window, and the daemon it registers runs under the systemd user unit like a package install.
- service install run from an AppImage registers the .AppImage file instead of the executable inside the runtime's temporary mount, which is gone once the process exits. The file is used only when the running executable is inside APPDIR, so a program started from another AppImage, whose APPIMAGE it inherits, still registers itself.
- The AppImage carries only the Avahi client libraries from the Debian 12 sysroot, with their LGPL-2.1 license, found through the binary's RUNPATH rather than LD_LIBRARY_PATH; glibc 2.35 or newer, ALSA, D-Bus and libxkbcommon come from the host, as for the packages.
- Its AppRun starts the binary as midi-harbor, so on X11 the window's class matches the desktop entry instead of the AppImage's file name.
- Building it needs the cross image's new patchelf, file, appimagetool 1.9.1 and type2 runtime 20251108, pinned by checksum, and a sysroot rebuilt to carry Avahi's license; the script stops and names make build-sysroot when that license is missing.

.goreleaser.yaml

@@ -31,6 +31,10 @@ builds:
       - CARGO_TARGET_X86_64_APPLE_DARWIN_RUSTFLAGS=-C link-arg=-Wl,-headerpad_max_install_names
       - CARGO_TARGET_AARCH64_APPLE_DARWIN_RUSTFLAGS=-C link-arg=-Wl,-headerpad_max_install_names
       - BINDGEN_EXTRA_CLANG_ARGS={{ if eq .Os "linux" }}-idirafter /sysroot/linux_{{ .Arch }}/usr/include -idirafter /sysroot/linux_{{ .Arch }}/usr/include/{{ if eq .Arch "amd64" }}x86_64{{ else }}aarch64{{ end }}-linux-gnu{{ end }}
+    hooks:
+      # GoReleaser's own edition makes no AppImages, so the script does, for each Linux target.
+      post:
+        - cmd: '{{ if eq .Os "linux" }}packaging/linux/appimage.sh "{{ .Path }}" "{{ .Arch }}" "{{ .Version }}" dist{{ else }}true{{ end }}'
 
   # The full build for the Mac, which ships only inside the app on the disk image, never in an
   # archive of its own.
@@ -188,6 +192,7 @@ checksum:
   name_template: checksums.txt
   extra_files:
     - glob: dist/*.dmg
+    - glob: dist/*.AppImage
 
 # A release takes its version from the tag, which make release checks against VERSION. A snapshot
 # has no tag, so it takes VERSION, which the Makefile passes in.
@@ -203,3 +208,4 @@ release:
     name: midi-harbor
   extra_files:
     - glob: dist/*.dmg
+    - glob: dist/*.AppImage

README.md

@@ -17,6 +17,7 @@ leaves out the graphical interface, for machines without a display.
 ```bash
 sudo apt install ./midi-harbor_<version>_<arch>.deb    # Debian and Ubuntu
 sudo dnf install ./midi-harbor-<version>-1.<arch>.rpm    # Fedora and RHEL
+chmod +x Midi-Harbor-<version>-x86_64.AppImage              # any other distribution
 ```
 
 The release builds need glibc 2.35 or newer, so RHEL 9 and its rebuilds must build from source.

crates/service/src/lib.rs

@@ -91,12 +91,25 @@ pub struct ServiceSpec {
 
 impl ServiceSpec {
     /// Builds a specification running the current executable as the daemon.
+    ///
+    /// From an AppImage it runs the AppImage file, since the running executable is inside a
+    /// mount that is gone once this process exits.
     pub fn for_current_executable() -> Result<Self, ServiceError> {
-        let executable = std::env::current_exe().map_err(|source| ServiceError::Io {
+        let running = std::env::current_exe().map_err(|source| ServiceError::Io {
             operation: "locate",
             path: PathBuf::from("the running executable"),
             source,
         })?;
+        // AppImages exist only on Linux.
+        #[cfg(target_os = "linux")]
+        let executable = appimage_file(
+            &running,
+            std::env::var_os("APPIMAGE"),
+            std::env::var_os("APPDIR"),
+        )
+        .unwrap_or(running);
+        #[cfg(not(target_os = "linux"))]
+        let executable = running;
         Ok(Self {
             executable,
             arguments: vec!["daemon".to_owned()],
@@ -191,6 +204,25 @@ pub fn detect() -> Result<Box<dyn ServiceManager>, ServiceError> {
     }
 }
 
+/// Returns the AppImage file the running executable was started from, if it was.
+///
+/// The AppImage runtime sets `APPIMAGE` to the file and `APPDIR` to where it mounted it, and
+/// every process started from the application inherits both. So the executable must be inside
+/// `APPDIR`, or the variables belong to another AppImage that started this program.
+#[cfg(target_os = "linux")]
+fn appimage_file(
+    running: &Path,
+    appimage: Option<std::ffi::OsString>,
+    appdir: Option<std::ffi::OsString>,
+) -> Option<PathBuf> {
+    let appdir = PathBuf::from(appdir?);
+    if appdir.as_os_str().is_empty() || !running.starts_with(&appdir) {
+        return None;
+    }
+    let appimage = PathBuf::from(appimage?);
+    appimage.is_absolute().then_some(appimage)
+}
+
 /// Reports whether the executable a registration points at still exists.
 pub(crate) fn is_stale(registered: Option<&Path>) -> bool {
     registered.is_some_and(|path| !path.exists())
@@ -235,3 +267,65 @@ pub(crate) fn run(command: &str, args: &[&str]) -> Result<String, ServiceError>
         },
     })
 }
+
+// AppImages exist only on Linux, and these paths are not absolute on Windows.
+#[cfg(all(test, target_os = "linux"))]
+mod tests {
+    use super::*;
+
+    /// Locks which executable a service registration names when the program runs from an
+    /// AppImage.
+    ///
+    /// The AppImage runtime (AppImage/type2-runtime, runtime.c) mounts the image at
+    /// `/tmp/.mount_<name><random>`, sets `APPDIR` to that mount and `APPIMAGE` to the image
+    /// file, and replaces itself with the application. The mount is gone once the application
+    /// exits, so a unit naming the executable inside it fails at the next login. Children inherit
+    /// both variables, so a program started from another AppImage, such as a terminal, sees that
+    /// AppImage's values while running from somewhere else entirely.
+    #[test]
+    fn a_registration_names_the_appimage_file_only_when_running_from_its_mount() {
+        let mount = "/tmp/.mount_MidiHaAbC123";
+        let inside = "/tmp/.mount_MidiHaAbC123/usr/bin/midi-harbor";
+        let cases = [
+            (
+                "running from the AppImage's mount",
+                inside,
+                Some("/home/user/Apps/Midi-Harbor-0.1.0-x86_64.AppImage"),
+                Some(mount),
+                Some("/home/user/Apps/Midi-Harbor-0.1.0-x86_64.AppImage"),
+            ),
+            (
+                "installed binary started from another AppImage's terminal",
+                "/usr/bin/midi-harbor",
+                Some("/home/user/Apps/Terminal.AppImage"),
+                Some("/tmp/.mount_TerminXyZ789"),
+                None,
+            ),
+            (
+                "installed binary with no AppImage involved",
+                "/usr/bin/midi-harbor",
+                None,
+                None,
+                None,
+            ),
+            (
+                "an empty APPDIR, which every path starts with",
+                inside,
+                Some("/home/user/Apps/Midi-Harbor-0.1.0-x86_64.AppImage"),
+                Some(""),
+                None,
+            ),
+        ];
+        for (name, running, appimage, appdir, want) in cases {
+            assert_eq!(
+                appimage_file(
+                    Path::new(running),
+                    appimage.map(Into::into),
+                    appdir.map(Into::into),
+                ),
+                want.map(PathBuf::from),
+                "{name}: the registration must name a file that outlives this process"
+            );
+        }
+    }
+}

docs/installation.md

@@ -35,6 +35,18 @@ anything newer. On RHEL 9 and its rebuilds, build from source. The packages reco
 BlueZ. Installing a package does not start anything. Each user who wants the daemon at login runs
 `midi-harbor service install --start`.
 
+**Any other Linux distribution**: `Midi-Harbor-<version>-<x86_64|aarch64>.AppImage` runs without
+installing. Keep it where it will stay, such as `~/Applications`, make it executable with
+`chmod +x`, and open it; it shows the graphical interface, which offers to start the daemon at
+login. The service runs the AppImage file itself, so moving a newer one over it updates the
+daemon at its next start; copying into it fails while the daemon runs. A newer one saved under
+another name leaves the registration stale until it is opened and set up again. The AppImage
+needs FUSE, which desktop distributions include, and a desktop's own libraries: ALSA, D-Bus and
+libxkbcommon. It carries the Avahi client libraries, so it still browses and advertises sessions
+where only the Avahi daemon is installed. Keep it away from AppImage's portable mode: a `.home` or
+`.config` directory beside the file moves where the service is registered, and systemd never
+finds it there.
+
 **Windows**: unpack `midi-harbor-<version>.windows-amd64.zip` somewhere it will stay, such as
 `%LOCALAPPDATA%\Programs\Midi Harbor`; the service remembers where it is. There is no installer.
 The executable is not signed, so the first time it runs Windows may show "Windows protected your

packaging/README.md

@@ -11,6 +11,7 @@ image that adds Rust to GoReleaser's cross-compiling image. It builds:
 | `tar.gz` archive, headless only | Linux and macOS, x86_64 and arm64 |
 | `zip` archive | Windows x86_64 |
 | `.deb` and `.rpm`, `midi-harbor` and `midi-harbor-headless` | Linux x86_64 and arm64 |
+| AppImage, with the graphical interface | Linux x86_64 and arm64 |
 | `.dmg` holding `Midi Harbor.app`, the license and the docs | macOS, one universal binary |
 | `checksums.txt` | all of them |
 
@@ -59,6 +60,19 @@ script renders to `MenuBarIcon.png`; keep it in step with `Icon.svg` by hand.
 The Windows executable carries the icon as a resource, compiled by `windres` from mingw-w64, or
 `rc.exe` when building with MSVC. A Windows build fails without one.
 
+## AppImage
+
+GoReleaser makes no AppImages, so `packaging/linux/appimage.sh` makes one from each full Linux
+binary, as `dist/Midi-Harbor-<version>-<x86_64|aarch64>.AppImage`, and the release publishes it.
+The image has `patchelf`, `appimagetool` and the AppImage runtime for both architectures, so the
+arm64 AppImage builds on an x86_64 machine and the other way round.
+
+The AppImage carries the binary, the desktop entry, the icon, the docs, and the Avahi client
+libraries from the Debian 12 sysroot with their license; the binary finds those through its
+RUNPATH. Its `AppRun`, `packaging/linux/AppRun`, starts the binary as `midi-harbor`, which on X11
+is the window's class and what the desktop entry's `StartupWMClass` names. Everything else comes from the host, as with the packages. Its license comes from the
+sysroot too, so after updating from a version without AppImages, run `make build-sysroot` again.
+
 ## macOS app and disk image
 
 GoReleaser makes app bundles and disk images only in its paid edition, so

packaging/cross/Dockerfile

@@ -51,3 +51,38 @@ RUN apt-get update; \
     cmake --build /tmp/libdmg/build --target dmg-bin -j "$(nproc)"; \
     install -m 0755 /tmp/libdmg/build/dmg/dmg /usr/local/bin/dmg; \
     rm -rf /tmp/rcodesign.tar.gz "/tmp/${name}" /tmp/libdmg
+
+# packaging/linux/appimage.sh builds the AppImages with these: patchelf points the binary at the
+# libraries bundled beside it, and appimagetool packs the tree behind the AppImage runtime for each
+# target architecture, running file to read each binary's. appimagetool is itself an AppImage,
+# unpacked here because a container has no FUSE to mount it with.
+ARG APPIMAGETOOL_VERSION=1.9.1
+ARG APPIMAGE_RUNTIME_VERSION=20251108
+RUN apt-get update; \
+    apt-get --no-install-recommends -y -q install file patchelf; \
+    rm -rf /var/lib/apt/lists/*; \
+    arch=$(uname -m); \
+    case "$arch" in \
+        aarch64) sum=f0837e7448a0c1e4e650a93bb3e85802546e60654ef287576f46c71c126a9158 ;; \
+        x86_64) sum=ed4ce84f0d9caff66f50bcca6ff6f35aae54ce8135408b3fa33abfc3cb384eb0 ;; \
+    esac; \
+    curl --proto '=https' --tlsv1.2 -sSfL -o /tmp/appimagetool.AppImage \
+        "https://github.com/AppImage/appimagetool/releases/download/${APPIMAGETOOL_VERSION}/appimagetool-${arch}.AppImage"; \
+    echo "$sum  /tmp/appimagetool.AppImage" | sha256sum -c -; \
+    chmod +x /tmp/appimagetool.AppImage; \
+    cd /opt; \
+    /tmp/appimagetool.AppImage --appimage-extract > /dev/null; \
+    mv squashfs-root appimagetool; \
+    chmod -R a+rX /opt/appimagetool; \
+    ln -s /opt/appimagetool/AppRun /usr/local/bin/appimagetool; \
+    rm /tmp/appimagetool.AppImage; \
+    mkdir -p /usr/local/share/appimage; \
+    for pair in \
+        x86_64:2fca8b443c92510f1483a883f60061ad09b46b978b2631c807cd873a47ec260d \
+        aarch64:00cbdfcf917cc6c0ff6d3347d59e0ca1f7f45a6df1a428a0d6d8a78664d87444; do \
+        runtime="/usr/local/share/appimage/runtime-${pair%%:*}"; \
+        curl --proto '=https' --tlsv1.2 -sSfL -o "$runtime" \
+            "https://github.com/AppImage/type2-runtime/releases/download/${APPIMAGE_RUNTIME_VERSION}/runtime-${pair%%:*}"; \
+        echo "${pair#*:}  $runtime" | sha256sum -c -; \
+        chmod 0644 "$runtime"; \
+    done

packaging/linux/AppRun

@@ -0,0 +1,8 @@
+#!/bin/bash
+# Starts Midi Harbor from inside its AppImage, under the name midi-harbor.
+#
+# The AppImage runtime passes the AppImage's own path as argv[0], and on X11 the window's class
+# is taken from argv[0], so without this the class would be the AppImage's file name and no
+# desktop would pair the window with its entry, whose StartupWMClass is midi-harbor. exec keeps
+# the process, so systemd's main process and the runtime's mount stay as they are.
+exec -a midi-harbor "${0%/*}/usr/bin/midi-harbor" "$@"

packaging/linux/appimage.sh

@@ -0,0 +1,81 @@
+#!/bin/sh
+# Wraps a built Linux binary into an AppImage.
+#
+#   packaging/linux/appimage.sh <binary> <amd64|arm64> <version> <output directory>
+#
+# The AppImage is Midi-Harbor-<version>-<x86_64|aarch64>.AppImage in the output directory. It
+# needs patchelf, appimagetool, the AppImage runtime for the target in
+# /usr/local/share/appimage/runtime-<x86_64|aarch64>, and the Debian 12 sysroot the binary was
+# linked against in /sysroot/linux_<arch>; the image packaging/cross/Dockerfile makes has the
+# tools, and GoReleaser runs it there with the sysroots mounted. MIDI_HARBOR_SYSROOT names another
+# directory holding the sysroots.
+#
+# Started with no arguments the AppImage opens the graphical interface, and `service install` run
+# from it registers the AppImage file itself, so systemd mounts it again at every start
+# (specs/017-appimage).
+#
+# It bundles only the Avahi client libraries, which a desktop may lack. glibc, ALSA, D-Bus and
+# libxkbcommon come from the host: a bundled libasound finds no sound cards, and the host's
+# libxkbcommon-x11, which the interface loads while it runs, is built against the host's
+# libxkbcommon (R-104).
+set -eu
+
+binary=$1
+arch=$2
+version=$3
+out=$4
+cd "$(dirname "$0")/../.."
+
+case "$arch" in
+    amd64) machine=x86_64 ;;
+    arm64) machine=aarch64 ;;
+    *)
+        echo "appimage.sh: unsupported architecture $arch" >&2
+        exit 1
+        ;;
+esac
+sysroot="${MIDI_HARBOR_SYSROOT:-/sysroot}/linux_$arch"
+libraries="$sysroot/usr/lib/$machine-linux-gnu"
+runtime="/usr/local/share/appimage/runtime-$machine"
+appdir="$out/appimage-$arch/AppDir"
+image="$out/Midi-Harbor-$version-$machine.AppImage"
+id=com.mrgeckosmedia.MidiHarbor
+
+# Check the sysroot is new enough to carry the bundled libraries' license.
+if [ ! -f "$sysroot/usr/share/doc/libavahi-client3/copyright" ]; then
+    echo "appimage.sh: $sysroot has no Avahi license; run make build-sysroot" >&2
+    exit 1
+fi
+
+# Assemble the tree. AppRun is what the runtime starts; it runs the binary under the name the
+# desktop entry expects.
+rm -rf "$appdir" "$image"
+mkdir -p "$appdir/usr/bin" "$appdir/usr/lib" "$appdir/usr/share/applications" \
+    "$appdir/usr/share/icons/hicolor/scalable/apps" "$appdir/usr/share/doc/midi-harbor" \
+    "$appdir/usr/share/doc/libavahi-client3"
+cp "$binary" "$appdir/usr/bin/midi-harbor"
+chmod 0755 "$appdir/usr/bin/midi-harbor"
+cp packaging/linux/AppRun "$appdir/AppRun"
+chmod 0755 "$appdir/AppRun"
+
+# Bundle the Avahi client libraries, found through the binary's RUNPATH rather than
+# LD_LIBRARY_PATH, which would reach every command the daemon runs.
+cp -L "$libraries/libavahi-client.so.3" "$libraries/libavahi-common.so.3" "$appdir/usr/lib/"
+patchelf --set-rpath '$ORIGIN/../lib' "$appdir/usr/bin/midi-harbor"
+
+# Desktop entry and icon, at the root where appimagetool looks and under usr/share where desktop
+# integration tools do.
+cp packaging/linux/$id.desktop "$appdir/$id.desktop"
+cp packaging/linux/$id.desktop "$appdir/usr/share/applications/$id.desktop"
+cp Icon.svg "$appdir/$id.svg"
+cp Icon.svg "$appdir/usr/share/icons/hicolor/scalable/apps/$id.svg"
+
+# Licenses and documentation.
+cp LICENSE.txt "$appdir/usr/share/doc/midi-harbor/copyright"
+cp docs/*.md "$appdir/usr/share/doc/midi-harbor/"
+cp "$sysroot/usr/share/doc/libavahi-client3/copyright" "$appdir/usr/share/doc/libavahi-client3/"
+cp "$sysroot/usr/share/common-licenses/LGPL-2.1" "$appdir/usr/share/doc/libavahi-client3/"
+
+# Pack it behind the runtime for the target.
+ARCH=$machine appimagetool --no-appstream --runtime-file "$runtime" "$appdir" "$image"
+rm -rf "$out/appimage-$arch"

packaging/sysroot/Dockerfile

@@ -20,3 +20,6 @@ RUN find /usr/lib -type l -lname '/*' | while read -r link; do \
 FROM scratch
 COPY --from=debian /usr/include /usr/include
 COPY --from=debian /usr/lib /usr/lib
+# The AppImage carries the Avahi client libraries, so it carries their license beside them.
+COPY --from=debian /usr/share/doc/libavahi-client3/copyright /usr/share/doc/libavahi-client3/copyright
+COPY --from=debian /usr/share/common-licenses/LGPL-2.1 /usr/share/common-licenses/LGPL-2.1

specs/017-appimage/research.md

@@ -0,0 +1,118 @@
+# Research: AppImage
+
+The investigation behind this spec, under its number in the project-wide research log.
+
+---
+
+## R-104: Whether an AppImage can carry the daemon
+
+**Status**: **VERIFIED** (2026-09-29) on Arch Linux (x86_64) and Ubuntu 22.04 (both
+architectures). Built as T246 and T247.
+
+**The runtime.** AppImage's type 2 runtime (AppImage/type2-runtime, `runtime.c`, release
+20251108) mounts the image through FUSE at `/tmp/.mount_<first six letters of the file name><six
+random characters>`, sets `APPIMAGE` to the file and `APPDIR` to the mount, and replaces itself
+with `AppRun`. A forked child serves the mount while any process holds the read end of a pipe it
+leaves open across `exec`, and exits once none does. The runtime is static and needs only a setuid
+`fusermount` or `fusermount3`, not libfuse2, so Ubuntu 22.04 and later run it as installed.
+
+**A daemon works under systemd.** The unit's `ExecStart` names the AppImage file, so every start,
+at login or after `Restart=always`, mounts it afresh. systemd tracks the process that became
+`AppRun`, and the mount's child runs in the same cgroup. The daemon replaces itself with `exec`
+only when CoreMIDI reports its server gone (R-079), which never happens on Linux; an `exec` would
+keep the mount in any case, since the process keeps the pipe.
+
+**Stopping has to be ordered.** systemd's default `KillMode=control-group` sends SIGTERM to every
+process in the unit at once. The mount's child unmounts on SIGTERM while the daemon is still
+shutting down, and the daemon then touches a page of its executable that was never read: every
+`systemctl --user stop` and every logout ended in SIGBUS and a core dump, before the daemon had
+released its notes. `KillMode=mixed` signals only the daemon, but SIGKILLs the rest the moment it
+exits, before the child can unmount, which left one dead mount in `/tmp` per stop. The unit
+therefore has an `ExecStop` that sends SIGTERM to `$MAINPID` and waits for it to exit. systemd
+then signals what remains as usual, by which time the child has seen its pipe close and unmounted.
+From a package there is nothing else in the unit, so it stops as before.
+
+After a crash, systemd's SIGTERM reaches only the child, which unmounts but leaves its empty
+directory in `/tmp`; a normal stop removes it. That is the runtime's behaviour and is cleared at
+reboot.
+
+**The unit must not name the running executable.** `current_exe` gives the path inside the mount,
+which is gone once the daemon exits, so a unit naming it fails at the next login. Programs started
+from an AppImage inherit both variables, so a copy installed from a package and started from an
+AppImage terminal sees that terminal's `APPIMAGE`. The registered executable is therefore the
+`APPIMAGE` file only when the running executable is under `APPDIR`.
+
+**Libraries.** The release binary links `libxkbcommon`, `libavahi-client`, `libavahi-common`,
+`libasound`, `libdbus-1`, `libm` and `libc`; the interface loads Wayland, X11, EGL and Vulkan while
+it runs. Only the two Avahi libraries are bundled, from the Debian 12 sysroot:
+
+- AppImage's excludelist (AppImageCommunity/pkg2appimage) names `libasound.so.2`, since a bundled
+  copy finds no sound cards, and the graphics libraries, which belong to the driver.
+- `libxkbcommon` stays with the host, whose `libxkbcommon-x11`, loaded by the interface, is built
+  against the host's own.
+- The Avahi client talks to the Avahi daemon over D-Bus, and a desktop may have the daemon without
+  the client library.
+
+The bundled libraries are found through the binary's RUNPATH, `$ORIGIN/../lib`, set with patchelf.
+`LD_LIBRARY_PATH` in `AppRun` would reach every command the daemon runs, such as `systemctl`.
+
+**The window on X11.** Tested in XFCE, the window was listed as "Untitled window" with the class
+`Midi-Harbor-0.1.0-x86_64.AppImage`, so no desktop paired it with its entry. Two causes, neither
+the AppImage's alone:
+
+- The GUI never set a window title, so every Linux desktop showed none; the header draws its own,
+  which is why it went unnoticed.
+- libcosmic at the pinned revision (`iced/winit/src/conversion.rs`) builds winit's X11 attributes
+  with the application ID as the window's name, then replaces them with the Wayland attributes, so
+  on X11 winit falls back to the file name of `argv[0]` for `WM_CLASS`
+  (`winit-x11/src/window.rs`). From a package that is `midi-harbor`; from an AppImage it is the
+  AppImage's file name, which the runtime passes as `argv[0]`. The desktop entry named
+  `com.mrgeckosmedia.MidiHarbor`, which only Wayland's application ID ever matched.
+
+The entry's `StartupWMClass` is now `midi-harbor`, and the AppImage's `AppRun` is a bash script
+that execs the binary with `exec -a midi-harbor`, so both builds carry that class. Wayland pairs by
+the application ID and the entry's file name, which are unchanged. `exec` keeps the process, so the
+unit's main process, the `ExecStop` and the runtime's mount behave as before.
+
+**Updating the file.** Writing into the AppImage while the daemon runs fails with "Text file busy",
+the mount's child running from it. Moving a new file over it works, and the daemon runs the new one
+from its next start.
+
+**Evidence**:
+
+- Arch Linux, fuse3 only: `service install --start` wrote
+  `ExecStart=/root/Apps/Midi-Harbor.AppImage daemon`; `/proc/<pid>/maps` showed both Avahi
+  libraries from the mount and `libasound`, `libdbus-1` and `libxkbcommon` from `/usr/lib`; the
+  ALSA sequencer's Midi Through port was listed; a network port was advertised on
+  `_apple-midi._udp` and `network discover` found Windows peers.
+- After `kill -9`, systemd started the daemon again within four seconds on a new mount, and the old
+  mount was gone.
+- With the unit as first written, `systemctl --user stop` and logging out both ended in
+  `code=dumped, status=7/BUS`. With the `ExecStop`, three stops in a row each logged "daemon
+  stopped", left no process and no mount, and a crash still restarted it.
+- Logging out, letting root's user manager stop, and logging in again over SSH started the unit
+  with `default.target`, which is what a login does. With the `ExecStop`, the logout stopped the
+  daemon cleanly and left one mount, the new daemon's.
+- Renamed to `Midi-Harbor-0.2.0-x86_64.AppImage`, `service status` reported the registration
+  stale, naming the old path, and `service install` from the new name repaired it.
+- Ubuntu 22.04, glibc 2.35, without Avahi: the arm64 AppImage ran through FUSE in a container.
+  The x86_64 one ran unpacked, since Docker's x86_64 emulation refuses the AppImage magic bytes
+  in the ELF header's padding, and resolved both Avahi libraries from the bundle.
+- The window, on the Arch VM's Hyprland session as its desktop user, offered to register with
+  systemd. A new AppImage's first launch took 22 seconds to show it, reading the image from the
+  VM's disk; later launches took three to six seconds, even with a fresh home directory and the
+  VM's page cache dropped, the host's cache still holding the image. The first two launches of the
+  first build were checked at about eight seconds and taken for failures before this was known.
+
+- XFCE on X11, as the desktop user: the window's "Install and start" registered
+  `ExecStart=/home/<user>/Applications/Midi-Harbor-0.1.0-x86_64.AppImage daemon`, started it, and
+  listed the ALSA Midi Through port. With the fixes the window is listed with the class
+  `midi-harbor` and the title "Midi Harbor", and launched through its desktop entry, as AppImage
+  integration tools install it, the taskbar shows the entry's icon.
+- A new build moved over the registered file while the daemon ran, then `systemctl --user restart`:
+  the old daemon logged "daemon stopped", the new one started, and no core dump.
+
+- A reboot with the service installed from the window: the daemon logged "daemon stopped" as the
+  machine shut down, and started from the AppImage 35 seconds later, when SDDM logged the user in.
+
+**Not checked**: an arm64 machine outside Docker.

specs/017-appimage/spec.md

@@ -0,0 +1,82 @@
+# Feature Specification: AppImage
+
+**Created**: 2026-09-29
+
+**Status**: Implemented; built for x86_64 and arm64 and checked on 2026-09-29 on Arch Linux and
+Ubuntu 22.04
+
+**Input**: User request: "I'd like to see what it'll take to make an app image of this project. I
+don't know if its something that'll allow a daemon process, so please research and see.", then
+"If you think its feasible, do it."
+
+The `.deb` and `.rpm` packages cover Debian, Ubuntu, Fedora and RHEL. Every other distribution had
+only the `.tar.gz` of the bare binary, with no desktop entry and no libraries. A release now
+carries an AppImage for each Linux architecture as well, which runs the graphical interface and
+the daemon it registers with systemd.
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Running Midi Harbor from an AppImage (Priority: P1)
+
+A user on a distribution without a package downloads the AppImage, makes it executable and opens
+it. The window offers to start the daemon at login, and from then on the daemon starts at every
+login and after every crash, as it does when installed from a package.
+
+**Why this priority**: it is the whole request.
+
+**Independent Test**: On a Linux machine with a systemd user session, run
+`service install --start` from the AppImage, then check the unit, the running daemon, a restart
+after the daemon is killed, and an advertised network port.
+
+**Acceptance Scenarios**:
+
+1. **Given** the AppImage, **When** `service install` runs from it, **Then** the unit starts the
+   AppImage file, not the executable inside its mount.
+2. **Given** the service installed from the AppImage, **When** the daemon is killed, **Then**
+   systemd starts it again from the AppImage.
+3. **Given** the daemon running from the AppImage, **When** the service is stopped or the user
+   logs out, **Then** the daemon shuts down as it does from a package, releasing its notes, and
+   leaves no mount behind.
+4. **Given** a distribution without the Avahi client libraries, **When** a network port is
+   created, **Then** it is advertised, the AppImage carrying the libraries.
+5. **Given** a newer AppImage moved over the registered one, **When** the daemon next starts,
+   **Then** it runs the newer one.
+6. **Given** a newer AppImage saved under another name and the old one deleted, **When**
+   `service status` runs, **Then** it reports the registration stale, and `service install` from
+   the new file repairs it.
+
+### User Story 2 - Building the AppImages (Priority: P1)
+
+`make snapshot` and `make release` build an AppImage for x86_64 and arm64 beside the other
+artifacts, and the release publishes them.
+
+**Independent Test**: Run the build and check both AppImages exist and start.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-I01**: `service install` run from an AppImage MUST register the AppImage file, and run from
+  anything else MUST register the running executable, whatever AppImage variables it inherited.
+- **FR-I04**: Stopping the service MUST let the daemon finish its shutdown before anything else in
+  the unit is stopped.
+- **FR-I02**: The release MUST build an AppImage for each Linux architecture it builds, from the
+  same binary as the packages.
+- **FR-I03**: The AppImage MUST run on the distributions the packages do, needing from the host only
+  glibc, FUSE and what a desktop already has.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-I01**: From a downloaded AppImage, the daemon runs at login after one setup step, the same
+  step as from a package.
+
+## Assumptions
+
+- The AppImage is for desktops. A server takes the headless archive or package, so there is no
+  headless AppImage.
+- Updates are by hand. AppImageUpdate's update information and `.zsync` file can be added later
+  without changing the daemon.
+- AppImage's portable mode, a `.home` or `.config` directory beside the file, is not supported:
+  it moves where the unit is written, where systemd does not look.

specs/017-appimage/tasks.md

@@ -0,0 +1,7 @@
+# Tasks: AppImage
+
+Tasks by their numbers in the project-wide sequence, which continues across every spec.
+
+- [x] T246 Register the AppImage file rather than the executable inside its mount, per FR-I01 and FR-I04 — done: `ServiceSpec::for_current_executable` takes `APPIMAGE` when the running executable is under `APPDIR`, so another AppImage's inherited variables are ignored; and the unit's `ExecStop` stops the daemon alone and waits for it, since stopping the whole unit at once unmounted the AppImage under the daemon and killed it with SIGBUS (R-104). Unit tested in `crates/service/src/lib.rs` against the variables the AppImage runtime sets, and in `crates/service/src/systemd.rs` for the `ExecStop`.
+- [x] T247 Build and publish an AppImage for each Linux architecture, per FR-I02 and FR-I03 — done: `packaging/linux/appimage.sh`, run by GoReleaser after each full Linux build, bundles the Avahi client libraries and their license from the sysroot, sets the binary's RUNPATH, and packs it with appimagetool and the pinned runtime, which the cross image now carries; the release and checksums include `dist/*.AppImage`. Checked on Arch Linux and Ubuntu 22.04 (R-104); not unit tested, since it is a build script.
+- [x] T248 Name the window on Linux so taskbars pair it with its desktop entry — done: the window's title is set to "Midi Harbor" at start, the desktop entry's `StartupWMClass` is `midi-harbor`, and the AppImage's `AppRun` runs the binary as `midi-harbor`, since the pinned libcosmic leaves the X11 class to `argv[0]` (R-104). Checked in XFCE on X11; not unit tested, since it is window-system wiring.

specs/README.md

@@ -27,6 +27,7 @@ exception is 014, whose task list started again at T001: its T001 to T034 are ci
 | [014-mac-app-store-mode](014-mac-app-store-mode/spec.md) | The sandboxed App Store build, run from the menu bar |
 | [015-mac-menus](015-mac-menus/spec.md) | The menus on macOS: File, Edit, View, Window and Help |
 | [016-app-store-submission](016-app-store-submission/spec.md) | Building the package App Store Connect takes |
+| [017-appimage](017-appimage/spec.md) | The AppImage for Linux, and registering the daemon from it |
 
 ## Where each number is
 
@@ -136,3 +137,10 @@ exception is 014, whose task list started again at T001: its T001 to T034 are ci
 - **Success criteria**: SC-S01
 - **Research**: R-103
 - **Tasks**: T245
+
+### 017-appimage
+
+- **Requirements**: FR-I01, FR-I02, FR-I03, FR-I04
+- **Success criteria**: SC-I01
+- **Research**: R-104
+- **Tasks**: T246–T248