Multiplexer Commands

nash mux manages the multiplexer server and the sessions it holds. It always targets a unix domain from your configuration, and it handles the Nash-specific work: installing the server binary, reporting protocol drift, and driving sessions.

nash mux is separate from the lower-level nash cli commands. nash cli talks to the multiplexer of the pane it runs in. nash mux talks to the server of a domain you name.

For the idea and the [mux] setting, start with Multiplexer Sessions.

Commands

Command	What it does
`nash mux status`	Show the server state, protocol versions, and binaries.
`nash mux list`	List sessions with their window, tab, and pane counts.
`nash mux start`	Start the server when it is not running.
`nash mux stop`	Stop the server. This closes every pane it owns.
`nash mux restart`	Stop and start. This closes every pane it owns.
`nash mux new <session>`	Create a session without showing it.
`nash mux connect <session>`	Show a session. It creates the session when it is missing.
`nash mux rename <old> <new>`	Rename a session.
`nash mux kill <session>`	Close every pane in a session.
`nash mux update`	Install the server binary by hand. Nash normally does this.

$ nash mux list
SESSION WINDOWS TABS PANES
default       1    2     3
work          2    4     6

Options

Option	Applies to	What it does
`--domain <name>`	All commands	Choose the unix domain. The default is the first unix domain.
`--json`	`list`	Print JSON instead of a table.
`--cwd <dir>`, `-- PROG ...`	`new`	Set the working directory and the program of the first pane.
`--yes`, `-y`	`stop`, `restart`, `kill`	Answer the confirmation, for scripts.
`--force`	`stop`, `restart`	Send `SIGKILL` when the server does not exit within 10 seconds.
`--class <name>`	`connect`	Switch a Nash that you started with `--class`.
`--new-gui`	`connect`	Always open a separate window.
`--dry-run`, `--from <path>`	`update`	Report without writing, or install a binary from another path.

stop, restart, and kill ask for confirmation. Without a terminal they stop and tell you to pass --yes.

new and connect start the server when it is not running. status, list, rename, and kill do not. They tell you to run nash mux start first.

nash mux new fails if a session of that name exists. Use nash mux connect to show an existing session.

Connect to a session

nash mux connect work behaves like tmux new -A -s work:

It creates the session when no session of that name exists.
It asks a running Nash to switch to that session.
It opens a separate window when no Nash is running, or when you pass --new-gui.

Without a name, nash mux connect uses your default_session.

A window that this command opens is not a child of the pane where you typed the command. Nash ends the process tree of a pane when the pane closes, so a window that was a child of that pane would close with it.

If the running Nash is older than your nash command, it cannot switch sessions. The command says so and opens a window instead. Update the application.

Check the server

Run nash mux status. Your paths and versions differ from this example.

$ nash mux status
Domain:          mux
Socket:          ~/.local/share/nash/sock
Server:          running (pid 4242)
Server version:  0.9.1 (protocol 48)
Sessions:        2 (1 attached client(s))
This build:      0.9.1 (protocol 48)
Server binary:   ~/Library/Application Support/nash/bin/nash-mux-server [installed] (0.9.1)
Bundled copy:    /Applications/Nash.app/Contents/MacOS/nash-mux-server (0.9.1)

The Server binary line ends with [installed], [bundled], or [env]. The label tells you which copy the next server start uses.

Where the server binary lives

Nash looks for nash-mux-server in this order:

The path in $NASH_MUX_SERVER, when it is set. This pins the path and skips the other steps.
nash-mux-server in the bin directory of the Nash data directory, but only while it reports the same version as the running Nash.
The copy next to the running executable, inside the application bundle.

The Nash data directory is ~/Library/Application Support/nash on macOS and $XDG_DATA_HOME/nash on Linux (~/.local/share/nash by default).

The server never runs from inside the application bundle. An application update replaces the bundle and removes the old one, which would delete the file that a server runs from. So when step 3 wins, Nash first copies the bundled binary into the bin directory of the data directory and starts that copy.

This arrangement started in Nash 0.7.0, when the server left the bundle. A server start installs the bundled copy when the installed copy is missing or reports another version. On macOS, nash update refreshes the installed copy too, as part of installing a new application.

nash mux update does the same copy by hand:

$ nash mux update
Source:          /Applications/Nash.app/Contents/MacOS/nash-mux-server (0.9.1)
Destination:     ~/Library/Application Support/nash/bin/nash-mux-server (0.9.0)
Installed ~/Library/Application Support/nash/bin/nash-mux-server (0.9.1)
The running server (0.9.0) still serves this build.  It keeps its own binary
until it stops.

Use --dry-run to see the versions without writing anything. Use --from <path> to install a binary from elsewhere.

A unix domain that sets its own serve_command skips this resolution and runs that command as written. A server binary inside a Cargo target/debug or target/release directory starts in place, so a source build runs what you just built.

Two platform notes:

Linux (AppImage). The bundled copy lives inside the AppImage mount, and the mount disappears with the Nash process that owns it. The installed copy lets a server outlive the AppImage that started it.
Windows. Windows refuses to replace an executable that a running process uses. If the install fails for that reason, Nash logs a warning and starts the bundled copy instead. A server start is never blocked.

Why updates never restart the server

Every pane is a child process of the running server. No upgrade can move those panes into a new process. So nash mux update installs the binary and leaves the running server alone, as tmux does. nash update and the automatic installs follow the same rule. The new binary serves the next server start.

nash mux restart is the explicit step that closes the panes and starts a server from the new binary. Run it when you are ready to lose them.

See Update Nash from the command line for how nash update treats a running server.

Protocol versions

The Nash window and the server must speak the same protocol version. They do not need the same release version. A server from an earlier release keeps serving a newer Nash as long as the protocol did not change between them.

Releases	Protocol
0.7.0 to 0.7.6	47
0.8.1 and later	48

The Kitty graphics work in Nash 0.8.1 raised the protocol to version 48. A server that started under an older release must be restarted before a newer Nash can attach to it.

When the versions differ, nash mux status tells you:

$ nash mux status
Domain:          mux
Socket:          ~/.local/share/nash/sock
Server:          running (pid 4242)
Server version:  0.7.6 (protocol 47)
This build:      0.9.1 (protocol 48)
Server binary:   ~/Library/Application Support/nash/bin/nash-mux-server [installed] (0.9.1)
Bundled copy:    /Applications/Nash.app/Contents/MacOS/nash-mux-server (0.9.1)

The running server speaks protocol 47 and this build speaks 48.
Run `nash mux restart` when you can close its panes; the restart installs and
runs the matching server.

The Nash window shows the same advice when it cannot attach for this reason.

Limits

One server per machine by default. A unix domain that does not set socket_path uses the same socket as every other one, and the daemon locks one pid file. So --domain selects configuration, not a second server. Give a domain its own socket_path and daemon_options to run two servers.

A cold server creates its own session. When nash-mux-server starts, it opens one window in its default session. So nash mux new work against a server that was not running leaves you with default and work.

Session restore and the multiplexer overlap. The saved layout records panes that live in the server. A restore spawns new panes and does not reattach the panes that still run, so it duplicates them. Reach a running session with nash mux connect, and keep the restore dialog for panes that the Nash window owns.

nash mux stop and nash mux restart need a Unix system. Every other subcommand works on all platforms. On Windows, end the nash-mux-server process instead.