Getting Started

Install: macOS · Linux · CLI and server only

After installing: First steps · Upgrading from 1.x · Beta builds

Requirements

macOS desktop app

Install with Homebrew:

brew install --cask muxy-app/tap/muxy

Or download it yourself:

1. From the latest release, download Muxy-<version>-arm64.dmg for Apple Silicon or Muxy-<version>-x86_64.dmg for Intel.
2. Drag Muxy to /Applications and open it.

To use muxy in your shell, choose Install Command Line Tool… from the app menu. It links ~/.local/bin/muxy.

The app updates itself, also when installed with Homebrew. Running terminals keep going through most updates.

Linux desktop app

Linux support is experimental, targeting Ubuntu 24.04 on x86_64 and ARM64, with glibc 2.39 or newer and a working Vulkan driver. See the platform limits and WebKit sandbox setup.

Choose the quick installer for in-app updates, a Debian package, or an AppImage. All three include the desktop app, CLI and server. Use one format per channel to avoid conflicting CLI commands.

Quick installer with in-app updates

Install the Ubuntu dependencies once:

sudo apt update
sudo apt install curl python3 ca-certificates libfreetype6 libfontconfig1 libxcb1 \
  libxkbcommon0 libxkbcommon-x11-0 libwayland-client0 libvulkan1 mesa-vulkan-drivers \
  libwebkit2gtk-4.1-0 xdg-utils xdg-desktop-portal bubblewrap xdg-dbus-proxy

Install the latest stable release as your normal user, without sudo. The installer detects your architecture and verifies the download:

curl -fsSL --proto '=https' --proto-redir '=https' \
  https://github.com/muxy-app/muxy/releases/latest/download/install-desktop-linux.py \
  | python3 - install

Open Muxy from Applications. The app, CLI and server install into ~/.local/share/muxy-desktop by default. Add ~/.local/bin to your shell's PATH to use muxy <folder> from a terminal.

Debian package

Download muxy-desktop_<version>_amd64.deb or muxy-desktop_<version>_arm64.deb from the latest stable release. Use dpkg --print-architecture to check which you need. In your download directory, replace the filename below with your download:

sudo apt install './muxy-desktop_<version>_amd64.deb'

APT installs the dependencies and adds Muxy to Applications, with muxy and muxy-server in /usr/bin.

AppImage

Install the runtime libraries above, then download Muxy-<version>-linux-x86_64.AppImage or Muxy-<version>-linux-arm64.AppImage from the latest stable release. Use uname -m to check: aarch64 means ARM64. Replace the filename below with your download and run it without sudo:

chmod +x './Muxy-<version>-linux-x86_64.AppImage'
'./Muxy-<version>-linux-x86_64.AppImage'

The first launch adds Muxy to Applications. AppImage uses system WebKitGTK. If FUSE is unavailable, append --appimage-extract-and-run when launching it.

Muxy keeps an unpacked copy in ${XDG_DATA_HOME:-$HOME/.local/share}/muxy-appimage/<bundle-id> so terminals can keep running after the window closes. This takes extra disk space. Use ./Muxy-<version>-linux-x86_64.AppImage --cli <arguments> for the bundled CLI, or choose Install Command Line Tool… in the app to link it into ~/.local/bin.

Updates

• Quick installer: the app checks automatically; Check for Updates checks now. Stable installs stay on stable; beta installs stay on beta.
• Debian package: stop the server and quit Muxy, then download the newer .deb and install it with sudo apt install. There is no Muxy APT repository, so apt upgrade alone does not update Muxy.
• AppImage: quit the app, then download and run the newer file. Running terminals stay alive. If you linked the CLI, choose Install Command Line Tool… again from the new app.

Debian packages and AppImages do not use the in-app updater.

Remove

Stop the local server in Settings → Server, then quit Muxy. Stopping the server ends its running terminals. Removal keeps your settings, projects and saved session data.

• Quick installer: run the command below. For beta, replace muxy-desktop with muxy-desktop-beta.

  python3 "${XDG_DATA_HOME:-$HOME/.local/share}/muxy-desktop/current/install.py" uninstall
  

• Debian package: run sudo apt remove muxy-desktop (or muxy-desktop-beta).

• AppImage: delete the downloaded file, its matching unpacked copy listed above, and any CLI link or Applications entry pointing into that copy. The entry is in ${XDG_DATA_HOME:-$HOME/.local/share}/applications/com.muxy.app.desktop (com.muxy-beta.app.desktop for beta). Do not delete a copy still used by another running app or server.

CLI and server only

For a Linux computer or Mac without the desktop app. This installs muxy and muxy-server.

Homebrew

brew install muxy-app/tap/muxy-cli

Update with brew upgrade muxy-cli. On a computer you will reach as a remote server, use the install script instead: SSH sessions often don't have Homebrew on PATH.

Install script

Set VERSION to the newest version on the releases page, without the leading v:

VERSION=2.1.0
curl -fsSL "https://github.com/muxy-app/muxy/releases/download/v$VERSION/install-muxy.sh" \
  | sh -s -- --version "$VERSION"
export PATH="$HOME/.local/bin:$PATH"

The script picks the build for your OS and architecture, verifies its checksum, and installs both commands into ~/.local/bin. Add the export line to your shell's startup file to keep them on PATH.

• Update: run it again with the new version and --replace.
• Another folder: add --install-dir PATH.

Check it

Run muxy --version and muxy-server --version, then muxy to open the terminal UI. Updating them never restarts a running server; stop it to switch to the new version.

Upgrading from Muxy 1.x

Muxy 1.x offers Muxy 2 as an update, or you can install Muxy 2 over it. Unless you already have projects or workspaces in Muxy 2, the first launch imports your 1.x setup: supported settings, shortcuts, local projects, workspaces, terminal tabs, the default shell, and extensions. Projects, workspaces, and extensions that could not be imported are listed, and your 1.x data stays where it was. To import again later, open Settings → Backup & Restore and choose Import installed 1.x; it adds to what you already have.

Some 1.x features work differently or are not in 2.x yet. Most extensions keep working; see Coming from 1.x.

Beta

The beta gets new features first. Muxy Beta installs alongside stable, with separate settings and session data.

• macOS: download the newest v<version>-beta.<N> pre-release from the releases page. The app updates to each new beta.
• Linux: append --channel beta to the quick-installer command (python3 - install --channel beta), or download a beta .deb or AppImage from the releases page. Use the same update method as stable. The quick installer and Debian package provide muxy-beta and muxy-server-beta.
• CLI and server only: give the install script a beta version, such as 2.1.0-beta.1143.

First steps

1. Add a project. Choose Add Project at the bottom of the sidebar, or press Cmd+O, and pick a folder.
2. Open a terminal. Cmd+T opens a tab in the project. Cmd+N opens one in Home.
3. Split it. Cmd+D splits right, Cmd+Shift+D splits down.
4. Quit freely. Terminals keep running in the background. Reopen Muxy and everything is where you left it.

Next

• How Muxy works: the server, sessions, and history.
• Projects, Terminal, and Keyboard shortcuts.
• Remote servers and Mobile.
• Settings and Troubleshooting.