~/mpmux/docs ❯ less reference/command-line/contents ↓

mpmux and mpmux-sessiond on the command line#

mpmux has three programs:

Program	What it is
`mpmux`	The terminal window.
`mpmux-sessiond`	The session host: keeps shells running without a window, serves them to your devices.
`mpmux-cli`	Drives both from scripts. See mpmux-cli reference.

The exact help text of each is in command-line help.

Each prints its version, commit and the libraries built into it with --version (or -V) and exits; mpmux --version opens no window. mpmux-cli version shows all of them, installed and running.

mpmux#

mpmux [options] [--command <program> [args...]]
mpmux [options] -- <program> [args...]

Start#

Option	What it does
`--cwd <dir>`	Start the shell (or program) in this directory.
`--command <program> [args...]`	Run this program instead of your shell. Everything after it is its arguments.
`-- <program> [args...]`	The same, tmux style: `mpmux -- htop`.
`--config <path>`	Read this config file instead of `~/.config/mpmux/config.toml`.
`--pie-menus <path>`	Read pie menus from this JSON file.
`--write-default-config <path>`	Write a config file with every default, then exit.
`--write-default-pie-menus <path>`	Write the built-in pie menus as JSON, then exit.

The shell is your login shell ($SHELL), with your normal setup.

Hosted sessions#

These options open a session from a session host instead of a local shell:

Option	What it does
`--sessiond-socket <path>`	A session host on this machine.
`--sessiond-iroh <target>`	A session host over Iroh: an endpoint id, an endpoint token, or a pairing invite.
`--sessiond-endpoint <host:port>`, `--sessiond-tcp <host:port>`	A session host over plain TCP (trusted networks only).
`--session <id>`	Attach this session.
`--create-session`	Create a new session and attach it.
`--session-label <label>`	Its name, with `--create-session`.
`--session-client-name <name>`	How this window shows up in the host's attachment list.
`--sessiond-device-id <id>`, `--sessiond-device-token-file <path>`	Credentials of this paired device.
`--sessiond-admin-token-file <path>`	The host's admin token, for owners managing their own host.

Examples:

# a new hosted session on this machine
mpmux --sessiond-socket "$XDG_RUNTIME_DIR/mpmux-sessiond.sock" \
  --create-session --session-label build

# back into it later
mpmux --sessiond-socket "$XDG_RUNTIME_DIR/mpmux-sessiond.sock" --session session-3

Inside the window, Session Management in the command palette does the same without options, also for paired remote hosts.

Container session host#

mpmux can start a session host in a Podman container and attach to it:

Option	What it does
`--container [name]`	Start or reuse the container and a session of the same name.
`--container-bind <address>`	Host address to bind (default `127.0.0.1`).
`--container-lan`	Bind on all addresses with authentication on, for pairing on a trusted LAN.
`--container-iroh`	Reach the container over Iroh relay instead.
`--container-iroh-relay-url <url>`	Another relay (default `https://relay.mightypainting.dev`).
`--container-iroh-key <path>`	Where the container's Iroh key is kept on the host.

See the Alpine session host container.

mpmux-sessiond#

mpmux-sessiond [transport and auth options] [command] [session-id]

Run it#

The packages install a systemd user service:

systemctl --user enable --now mpmux-sessiond.service
journalctl --user -u mpmux-sessiond -f

It runs mpmux-sessiond --socket %t/mpmux-sessiond.sock serve: a local socket only, no network. To make it reachable from your other devices, add authentication and Iroh as shown in chapter 8.

Never start a second mpmux-sessiond serve by hand on the socket of a running one: the service then fails with "refusing to replace live Unix socket".

Options#

Option	What it does
`--socket <path>`	Listen on (or, for other commands, talk to) this Unix socket. Default: `$MPMUX_SESSIOND_SOCKET_PATH`, else `/run/user/<uid>/mpmux-sessiond.sock`.
`--tcp <host:port>`	Listen on plain TCP. Unencrypted.
`--tcp-allow-non-loopback`	Allow `--tcp` on an address other than 127.0.0.1. Only behind WireGuard or a similar tunnel.
`--auth-store <path>`	Turn authentication on; paired devices and invites live in this file (hashes only).
`--admin-token-file <path>`	The owner's admin token.
`--iroh-listen`	Accept devices over Iroh (encrypted, through NAT).
`--iroh-relay-url <url>`	The relay to use (run your own).
`--iroh-key <path>`	The host's Iroh key; created on first start. Its public half is the host's address.
`--iroh-allow-direct`	Let devices on the same network connect directly instead of through the relay.
`--json`	JSON output for the commands below.

Commands#

serve (the default) runs the host. The others are for checking on a host and for scripts on the same machine:

Command	What it does
`ping`	Is a host listening?
`status`, `metadata`	Its state and its fixed facts (version, protocol, capabilities).
`list-sessions`	Its sessions.
`create-session --label <name>`	A new session.
`rename-session <id> <name>`	Rename one.
`attach-session <id> --client-name <name>`, `detach-session <id>`	Mark a session as attached or not.
`delete-session <id>`	End a session and its shell.
`snapshot-session <id>`	Its screen and state.
`send-session-text <id> --text <text>`	Type into it.
`resize-session <id> <cols> <rows>`	Change its size.

mpmux-cli session … offers the same and more, also for remote hosts.

Environment variables#

Set by mpmux in each pane:

Variable	Meaning
`MPMUX_SOCKET_PATH`	The window's host-control socket; `mpmux-cli` uses it.
`MPMUX_HOSTED_SESSION_ID`	Set by the session host in hosted sessions: the session's id.

Read by mpmux and its tools:

Variable	Used by	Meaning
`MPMUX_SOCKET_PATH`	`mpmux`, `mpmux-cli`	Where the window listens / where to find it.
`MPMUX_HOST_CONTROL_TCP`	`mpmux-cli`	A host-control bridge over TCP, as `host:port`.
`MPMUX_SESSIOND_SOCKET_PATH`	all	The session host's socket.
`MPMUX_SESSIOND_ADMIN_TOKEN_FILE`, `MPMUX_SESSIOND_ADMIN_TOKEN`	`mpmux-cli`	Admin credentials for `mpmux-cli session` and `pair`.
`MPMUX_SESSIOND_DEVICE_ID`, `MPMUX_SESSIOND_DEVICE_TOKEN_FILE`, `MPMUX_SESSIOND_DEVICE_TOKEN`	`mpmux-cli`	Paired-device credentials.
`MPMUX_SESSIOND_IROH_KEY`	`mpmux`	This window's Iroh client key (`mpmux-cli` takes `--sessiond-iroh-key`; default `~/.config/mpmux/iroh/client.key`).
`MPMUX_EXTENSION_PATHS`	`mpmux`	Where runtime extensions are found.
`MPMUX_DEBUG`	`mpmux`	Debug logging for areas such as `input` (developers).
`XDG_CONFIG_HOME`	all	Base of `mpmux/config.toml`, `profiles.toml`, `pie-menus.json`.

Prefer the …_FILE variants for secrets: a token in an environment variable shows up in process listings of the same user and in crash reports.

Files#

Path	What it holds
`~/.config/mpmux/config.toml`	Settings. Reference.
`~/.config/mpmux/pie-menus.json`	Pie menus (optional).
`~/.config/mpmux/profiles.toml`	Session hosts for `mpmux-cli tui`.
`~/.config/mpmux/auth/`	Admin token, auth store, saved device credentials. Secret.
`~/.config/mpmux/iroh/`	Iroh keys. Secret.
`/run/user/<uid>/mpmux.sock`	The window's host-control socket.
`/run/user/<uid>/mpmux-sessiond.sock`	The session host's socket.
`~/.config/systemd/user/mpmux-sessiond.service.d/`	Your overrides for the service.