Installing mpmux preview releases#

Supported preview artifacts#

Arch users install from the signed repository. See docs/INSTALL_ARCH.md.

Ubuntu 22.04+ and Debian 12+ install from the signed apt repository:

sudo curl -fsSLo /usr/share/keyrings/mpmux-archive-keyring.gpg \
  https://mightypainting.dev/mpmux/apt/mpmux-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/mpmux-archive-keyring.gpg] https://mightypainting.dev/mpmux/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/mpmux.list
sudo apt update && sudo apt install mpmux
systemctl --user enable --now mpmux-sessiond   # optional

The .deb has no Whistle voice input: its speech engine needs glibc 2.38, newer than the package's Ubuntu 22.04 base. The Arch package, the macOS app on Apple silicon and the Android app have it.

Coding agents: mpmux-cli agents install installs mpmux's integrations into Claude Code and Pi (the todos sidebar, the run monitor, the skills); they update with mpmux. See guide chapter 12.

How the .deb and the Apple builds are made: docs/PACKAGING.md.

On the Linux desktop the Viewer shows web pages with an optional web engine (Chromium through CEF, about 320 MB). mpmux downloads it when you ask (Install Web Engine in the command palette) into ~/.local/share/mpmux/web-engine; no package installs it, and removing that folder removes it.

The authoritative machine-readable matrix is packaging/release-targets.json. A missing artifact, checksum, signature, or validation record is a release BLOCK, not implied success.

Linux requirements#

The preview bundle targets x86_64 Linux with glibc 2.39 or newer. Release validation rejects binaries that require a newer baseline. The desktop client dynamically uses Wayland or X11 plus common desktop audio/input libraries, including libwayland-client, libwayland-egl, libxkbcommon, libX11, libXcursor, ALSA/PulseAudio, and OpenSSL 3. The exact package names vary by distribution.

The headless mpmux-sessiond and mpmux-cli binaries have a smaller runtime surface and can be used without launching the GUI.

Verify and install the Linux bundle#

Download the tarball, release-manifest.json, release-manifest.json.minisig, linux-release.minisign.pub, and SHA256SUMS into one directory. Independently confirm minisign key id 4DF7261C21ADB3EE, then verify before extracting:

minisign -V \
  -p linux-release.minisign.pub \
  -m release-manifest.json \
  -x release-manifest.json.minisig
sha256sum --check SHA256SUMS

Inspect the manifest's version, commit, target, size, and digest if desired:

python3 -m json.tool release-manifest.json

Install for the current user:

mkdir -p ~/.local/src/mpmux
cd ~/.local/src/mpmux
tar -xzf ~/Downloads/mpmux-0.1.0-linux-x86_64.tar.gz
./mpmux-0.1.0-linux-x86_64/install.sh
systemctl --user daemon-reload

Use a custom prefix by passing it explicitly:

./mpmux-0.1.0-linux-x86_64/install.sh /opt/mpmux

The generated user service contains that exact prefix. The default ~/.local install requires ~/.local/bin on PATH.

First launch#

Standalone local terminal:

mpmux

Optional detachable local sessions (Linux; for macOS see the session host):

systemctl --user enable --now mpmux-sessiond.service
mpmux --sessiond-socket "$XDG_RUNTIME_DIR/mpmux-sessiond.sock" \
  --create-session --session-label shell

The installed service is local-only. It does not enable TCP, Iroh, auth, or Android pairing automatically.

macOS: mpmux-cli on the PATH#

Shells in mpmux find mpmux-cli without setup: on macOS mpmux appends mpmux.app/Contents/MacOS to the PATH of the shells it starts. To use it in other terminals too, link it into a folder on your PATH:

sudo mkdir -p /usr/local/bin
sudo ln -sf /Applications/mpmux.app/Contents/MacOS/mpmux-cli /usr/local/bin/mpmux-cli

Move the app to Applications first; a link into an app that macOS runs from a temporary location (a download not yet moved) breaks.

macOS: the session host#

The app bundle contains mpmux-sessiond. macOS has no systemd; mpmux-cli service install sets up a launchd LaunchAgent for it instead.

1. Move mpmux.app to /Applications and open it once, so macOS has checked the signature.
2. Install and start the session host (local only: a Unix socket, nothing reachable from the network):

sh /Applications/mpmux.app/Contents/MacOS/mpmux-cli service install

Use --dry-run first to see the LaunchAgent and the launchctl commands without changing anything. Add --remote to also enable authentication and Iroh, so phones and other computers can pair with this Mac (Across machines). 3. Check it:

sh /Applications/mpmux.app/Contents/MacOS/mpmux-cli service status

4. Open a session that outlives the window:

sh /Applications/mpmux.app/Contents/MacOS/mpmux --create-session --session-label shell

On macOS mpmux and mpmux-cli find the session host's socket ($TMPDIR/mpmux-<uid>/mpmux-sessiond.sock) without --sessiond-socket.

What the install sets up:

launchd starts agents with a bare environment, so the sessions get SHELL, PATH and LANG from the shell you run install in. After changing your PATH, run service install --restart to pass the new one on. A restart ends the host's shells.

After an app update, restart the host so it runs the new mpmux-sessiond (this ends its shells):

/Applications/mpmux.app/Contents/MacOS/mpmux-cli service install --restart

mpmux-cli service uninstall stops the host and removes the LaunchAgent; pairings, keys and the admin token stay in ~/.config/mpmux. Keep the Mac awake while other devices use it (System Settings → Energy, or sudo pmset -a sleep 0).

Which version is installed#

Each tool prints its version, commit and the libraries built into it:

mpmux --version
mpmux-sessiond --version
mpmux-cli --version

mpmux-cli version lists them all at once: this mpmux-cli, the mpmux and mpmux-sessiond it finds (next to itself, on PATH, or in mpmux.app on macOS), and the mpmux app and session host that are running. Binaries older than this option say "no version recorded". In the app, the command palette entry About mpmux shows the same, on Android too.

mpmux 0.1.6 (7953a9d9a02b)
  protocol       23
  platform       linux-x86_64
  libghostty-vt  7ec9e26a2939
  makepad        62691a290eb5 + 33 mpmux patches
  iroh           1.2.0

libghostty-vt and Makepad are built from pinned commits, so they show a commit; the Makepad line also counts the mpmux patches on top of it.

Update and rollback#

Keep the previous extracted bundle until the new version passes a launch and session smoke.

# Update
./mpmux-NEW-linux-x86_64/install.sh
systemctl --user daemon-reload
systemctl --user restart mpmux-sessiond.service

# Roll back
./mpmux-OLD-linux-x86_64/install.sh
systemctl --user daemon-reload
systemctl --user restart mpmux-sessiond.service

Hosted processes are tied to the running daemon. Schedule daemon restarts when interrupting hosted sessions is acceptable. Keep auth stores and endpoint keys under ~/.config/mpmux backed up separately; installers do not overwrite them.

Uninstall#

A package: sudo pacman -R mpmux (Arch) or sudo apt remove mpmux (Ubuntu, Debian). The bundle:

mpmux-uninstall

or, for a custom prefix:

/path/to/prefix/bin/mpmux-uninstall /path/to/prefix

The uninstaller disables the packaged user service and removes only files in the installed manifest. It does not delete user configuration, auth stores, keys, terminal history, or work directories.

Android APK#

Verify that the APK comes from the same release manifest, then install with Android's package installer or ADB:

adb install --replace mpmux-0.1.0-android-aarch64.apk
adb shell dumpsys package dev.mightypainting.mpmux | grep versionCode

Package id: dev.mightypainting.mpmux.

Android updates must retain signer continuity. Release packaging requires MPMUX_ANDROID_SIGNER_SHA256 to match the expected production certificate and rejects CN=Android Debug. A debug, mismatched, or unsigned package remains blocked from release. The in-app updater additionally requires a signed update manifest; see docs/ANDROID_RELEASE_SIGNING.md and docs/ANDROID_SELF_UPDATE.md.

Continue with docs/QUICKSTART.md for pairing and tablet use.