Multiplexer Sessions#

Normally every pane lives inside the Nash application. When Nash exits, the shells and the programs in them exit too. Session Restore brings the layout back, but the programs start again in new shells.

The multiplexer keeps the programs themselves alive. In multiplexer mode, a headless server owns your panes. A Nash window is only a view onto that server. Closing the window normally detaches the mux domain; quitting or updating Nash also leaves its server panes running. Explicitly closing a tab or pane ends its processes.

If you use tmux or screen to keep work running, this is the Nash version of that idea, built into the terminal.

Multiplexer sessions need Nash 0.5.6 or newer.

The pieces#

Piece	What it is
`nash-mux-server`	A headless process that owns panes. Panes survive the Nash window.
Session	A named workspace inside the server. It is the equivalent of a tmux session.
Domain	The connection to a server. `nash mux --domain <name>` selects one.

A session holds windows, a window holds tabs, and a tab holds panes. The server starts on demand, so you do not start it yourself.

Turn it on#

Multiplexer mode ships disabled. Edit the [mux] table in nash.toml:

[mux]
enabled = true
domain = "mux"
default_session = "default"
connect_automatically = true

Key	Default	What it does
`enabled`	`false`	Makes the multiplexer the default home for new panes.
`domain`	`"mux"`	The name of the unix domain. `nash mux --domain <name>` uses it too.
`default_session`	`"default"`	The session that a fresh start uses.
`connect_automatically`	`true`	Attaches the domain when Nash starts.

With enabled = true, Nash attaches the domain at startup and puts every new tab in it. Your panes then survive closing a window, quitting Nash, and updating the application. Restart Nash after you change the setting.

With connect_automatically = false, Nash does not attach the domain at startup. Run nash connect mux to attach it by hand.

With enabled = false, every pane stays inside the Nash application. The built-in local domain stays available in both modes, so a task that must not depend on the server can still spawn there.

If your nash.toml has no [mux] table, run nash config sync to add the table that your build ships. See Keep your configuration in step.

Reach your panes again#

After you close a window or quit Nash, the panes keep running in the server. Show a session again with either of these:

nash mux connect default

or choose Switch Session from the command palette.

nash mux connect <session> behaves like tmux new -A -s <session>. It creates the session if it does not exist, asks a running Nash to show it, and opens a new window if no Nash is running. The full command list is on the Multiplexer Commands page.

Sessions in the command palette#

The command palette has three session commands, in the Window menu:

Command	What it does
Switch Session	Pick a session and show it in this window.
New Session	Ask for a name, create the session, and switch to it.
Rename Session	Rename the session that this window shows.

These commands work on workspaces, so they are also useful when [mux].enabled = false. Only the server makes a session outlive the application.

The session badge#

Since Nash 0.11.1, a window whose panes live in a mux server shows the name of its session in a pill at the right end of the tab bar, as tmux shows the session name in its status line. A window that holds only local panes shows no badge. When a session gets a new name, the badge shows the new name at once.

When the tabs fill the row, the badge lies over them, and the tabs keep their size. A click on the badge acts as a click on the empty part of the tab bar, so you can drag the window by it.

The [mux.badge] table of nash.toml controls the badge:

[mux.badge]
enabled = true
font_size = 14
text_color = ""
background_color = "rgba(255,255,255,90%)"

Key	Shipped value	What it does
`enabled`	`true`	Shows the badge. `false` hides it.
`font_size`	`14`	Size of the name in points. `""` uses the size of tab titles.
`text_color`	`""`	Color of the name. `""` uses the theme accent.
`background_color`	`"rgba(255,255,255,90%)"`	Color of the pill. `""` uses the default white at 90% opacity.

The badge is never taller than the tab bar, and Nash cuts a name that is wider than 40% of the tab bar.

Folded panes and the multiplexer#

Folded panes survive a multiplexer reconnect. The fold state travels over the connection between the window and the server.

Keyboard input in 0.11.5#

Since Nash 0.11.5, the server reports each pane's keyboard encoding and whether it distinguishes Shift+Enter from Enter. The GUI uses that state for mux input, including Kitty and Win32 encoding, rather than assuming a local pane's keyboard mode. 0.11.5 uses protocol 50; 0.11.9 uses protocol 51. Clients and server must match. See Protocol versions before upgrading a running server.

Shared tab state in 0.11.9#

Since Nash 0.11.9, the server owns mux tabs' order, color, tab-scoped Zen Mode, and active panes. Changes reach other attached clients and survive a detach and reattach while the server keeps running. Tab dragging, Move Tab, and New Tab to the Right update the server's order. In mixed local/mux windows, only the mux tabs take part; other domains' tabs keep their slots.

A fresh attach selects the server's active tab in each window. Later resyncs leave your selected tab alone. Global Zen Mode and Back/Forward tab history stay GUI-local; history starts empty on attach. The tab's Zen flag is shared, but each GUI keeps its own Zen scope and dimming preferences. This does not add tab ordering to tmux control-mode domains.

Move Tab to New Window moves the existing server tab and its panes without restarting programs. Other clients learn the new window membership. The tmux control-mode restriction still applies. Splitting a server-owned tab into a different domain is rejected; use the tab's own domain for its splits.

Pane information and actions in 0.11.9#

The server supplies the foreground program and process group, TTY, alternate-screen state, and password-input metadata. Smart titles, folded-pane labels, tab search, password detection, and mouse-wheel handling use that server state, which can lag by a network trip. A fresh attach also receives existing user variables and the TTY; it does not replay user-var-changed for the initial snapshot.

Close confirmation asks the server whether a pane is safe to close. Its skip_close_confirmation_for_processes_named setting and Lua mux-is-process-stateful hook decide; a GUI-only hook does not override them. A failed or timed-out query keeps the confirmation prompt.
Process trees from pane:get_foreground_process_info() come from the server, or return nil on failure or timeout. Avoid repeated queries in high-frequency title or status callbacks.
Prompt navigation and semantic selection query server-side zones. Enable shell integration in the server pane. Successful results are cached for the pane's output sequence. A failure acts as no zones for that GUI action and retries next time; Lua pane:get_semantic_zones() raises an error instead.

These on-demand queries wait at most about 500 ms each. They do not provide compatibility with older servers. For TLS and multiplexing SSH domains, process names, PIDs, and executable paths describe the server's host, not local processes. An ordinary ssh command in a local pane only exposes the local ssh process. Project manifests remain disabled for TLS and SSH mux panes; a remote working directory does not authorize reading local files.

ResetTerminal and Lua pane:inject_output() change the server terminal for all attached clients, not the program's input. Non-inline iTerm2 file downloads are forwarded to attached GUIs; each GUI applies its own download policy and saves to its own Downloads directory. More than one GUI can receive the file.

Multiplexer or session restore?#

	Session Restore	Multiplexer
Layout comes back	Yes	Yes
Running programs keep going	No, Nash starts new shells	Yes
Needs a setting	No	Yes, `[mux].enabled = true`
Survives a machine restart	The layout does	No, the server stops

You can use both. Since 0.11.9, GUI saves omit fully detachable mux windows and retain only restorable local content from mixed layouts. Reconnect with nash mux connect for the server's still-running panes; a GUI save cannot checkpoint or restart the server. See Session Restore.