Skip to main content

Installation

pmux is a single binary with no runtime dependencies beyond tmux. It supports macOS and Linux on both arm64 and amd64 architectures.

Requirements​

info

pmux requires tmux but does not bundle it. Install tmux via your system package manager if you don't have it.

Homebrew​

brew install shiftinbits/tap/pmux

This is the preferred method for macOS and Linux systems with Homebrew. It handles updates automatically via brew upgrade.

Binary download​

Pre-built binaries for each release are available on the GitHub Releases page.

Download the archive for your platform, extract it, and move the binary into your PATH. For example, on macOS:

curl -LO https://github.com/ShiftinBits/pmux-agent/releases/latest/download/pmux-agent_0.5.3_Darwin_universal.zip
unzip pmux-agent_0.5.3_Darwin_universal.zip
sudo mv pmux /usr/local/bin/

On Linux, download pmux-agent_<version>_Linux_x86_64.tar.gz or pmux-agent_<version>_Linux_arm64.tar.gz instead (.deb and .rpm packages are also published). Replace the version with the latest release shown on the releases page.

Verifying the checksum​

Each release publishes a checksums.txt alongside the binaries. To verify your download before installing:

curl -LO https://github.com/ShiftinBits/pmux-agent/releases/latest/download/checksums.txt
shasum -a 256 --check --ignore-missing checksums.txt

Expected output is the archive filename followed by OK. If verification fails, delete the download and fetch it again — do not install an archive that fails its checksum.

Verify installation​

pmux --version

Expected output:

pmux version X.Y.Z

If the command is not found, confirm the binary location is in your PATH.

Troubleshooting​

pmux: command not found​

The directory holding the binary is not in your PATH.

  • Homebrew installs: run brew --prefix and confirm <prefix>/bin is in your PATH (echo $PATH). Apple Silicon Homebrew uses /opt/homebrew/bin, which shell setups sometimes miss — add eval "$(/opt/homebrew/bin/brew shellenv)" to your ~/.zprofile.
  • Manual installs: confirm the binary landed in a PATH directory (ls -l /usr/local/bin/pmux) and is executable (chmod +x).
  • After changing shell config, open a new terminal or run hash -r so the shell re-scans PATH.

macOS Gatekeeper blocks the binary​

If macOS reports "pmux" cannot be opened because it is from an unidentified developer (typical for a browser-downloaded binary), the file carries the quarantine attribute. Remove it:

xattr -d com.apple.quarantine /usr/local/bin/pmux

Alternatively, approve it under System Settings → Privacy & Security → Open Anyway. Homebrew installs are not quarantined and don't hit this.

tmux not found​

pmux requires tmux on the host. If pmux starts but complains about tmux, install it (brew install tmux, apt install tmux, dnf install tmux) and confirm tmux -V reports 3.x or later.

Checksum verification fails​

A failed shasum --check means the download is corrupt or incomplete. Delete both the archive and checksums.txt, re-download from the GitHub Releases page, and verify again. If it fails repeatedly, open an issue.

Next steps​

Continue to Initialization to generate your identity and set up pmux.

Last updated on