Installation

What you install

Two binaries:

They are produced from the same Swift Package and are designed to live next to each other on PATH. The client will auto-launch the daemon when it cannot find one running, but only if it can find a vmuxd next to itself or via $VMUX_DAEMON_PATH. Install them together.

Prerequisites

• macOS 14 Sonoma or later (Apple silicon or Intel)
• Xcode 16 or the matching Swift 6.2 toolchain
• About 200 MB of disk for build artifacts

You do not need Xcode itself open; the command-line tools are sufficient.

Build from source

The daemon lives in the Daemon/ directory of the vmux source tree as a standalone Swift Package.

git clone https://github.com/<org>/vmux.git
cd vmux
swift build --package-path Daemon -c release

Output goes to Daemon/.build/release/:

ls Daemon/.build/release/vmux Daemon/.build/release/vmuxd

Both files are statically linked against Swift runtime libraries and have no external .dylib dependencies you need to ship.

Install on PATH

Copy them somewhere on your PATH. The convention is /usr/local/bin:

sudo install -m 0755 Daemon/.build/release/vmux  /usr/local/bin/vmux
sudo install -m 0755 Daemon/.build/release/vmuxd /usr/local/bin/vmuxd

If you keep tools in ~/.local/bin or a Homebrew-managed prefix, install there instead:

install -m 0755 Daemon/.build/release/vmux  ~/.local/bin/vmux
install -m 0755 Daemon/.build/release/vmuxd ~/.local/bin/vmuxd

The auto-start logic finds vmuxd by looking next to the vmux binary first, then falling back to vmuxd on PATH. As long as both files end up in the same directory, no further configuration is needed.

Verify the install

which vmux vmuxd
vmux --help        # currently prints "unknown argument: --help" — see note below
vmuxd --help       # likewise

Both binaries reject unknown flags as a hard error, so a successful build is best confirmed by running:

vmuxd --socket /tmp/vmux-test.sock &
vmux  --socket /tmp/vmux-test.sock ls
kill %1

vmux ... ls should print one line for the auto-created default session. If you see that line, both binaries are working and they can talk over a Unix socket.

Optional: pin a custom daemon

If you keep the daemon binary somewhere unusual (for example a versioned release directory), set:

export VMUX_DAEMON_PATH=/opt/vmux/2026.05/bin/vmuxd

This overrides the sibling-of-vmux lookup and the PATH fallback. It is read every time vmux decides to auto-start a daemon, so you can change the value between invocations to switch versions without editing config.

Optional: launchd-managed daemon

The simplest setup is no setup: let the client auto-launch the daemon on first attach. If you would rather have the daemon come up at login and stay up across reboots, write a per-user LaunchAgent:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>app.vmux.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/vmuxd</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/vmuxd.out.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/vmuxd.err.log</string>
</dict>
</plist>

Install it as ~/Library/LaunchAgents/app.vmux.daemon.plist and load with:

launchctl load -w ~/Library/LaunchAgents/app.vmux.daemon.plist

Once managed by launchd, do not also start the daemon manually — you will get socket-already-in-use errors.

Uninstall

Stop any running daemon, remove the binaries, and (optionally) delete the config and socket:

# Stop a running daemon (any of the following work; see /docs/apps/daemon/vmuxd-server)
pkill -INT vmuxd

# Remove binaries
sudo rm /usr/local/bin/vmux /usr/local/bin/vmuxd
# or
rm ~/.local/bin/vmux ~/.local/bin/vmuxd

# Remove config (optional)
rm -rf ~/.config/vmux ~/.vmux

# Remove the socket if it was orphaned
rm -f /tmp/vmux-$(id -u).sock

If you installed a LaunchAgent, also unload and remove the plist:

launchctl unload -w ~/Library/LaunchAgents/app.vmux.daemon.plist
rm ~/Library/LaunchAgents/app.vmux.daemon.plist

vmux does not write any other files outside the config directory and the socket path.

Upgrading

Upgrades are a binary swap. To replace a running daemon without losing in-flight session state, stop, copy, and start:

pkill -INT vmuxd
sudo install -m 0755 Daemon/.build/release/vmux  /usr/local/bin/vmux
sudo install -m 0755 Daemon/.build/release/vmuxd /usr/local/bin/vmuxd
# next vmux invocation will auto-start the new daemon
vmux ls

Active sessions do not survive the daemon process — if you need to keep them, finish the work first or detach and reconnect via screen/tmux to the host.

Next steps

• vmuxd reference — server flags and signals.
• Configuration file — pin socket, shell, and default session.
• Shell integration — make vmux part of your normal shell startup.