mpmux quickstart#

This guide starts with safe local use, then adds an Android client through the encrypted Iroh relay path.

1. Launch a local terminal#

mpmux

Useful defaults:

• Ctrl-Shift-O — split right
• Ctrl-Shift-E — split down
• Ctrl-Alt-Arrow — move pane focus
• Ctrl-Shift-T — new tab
• Ctrl-Shift-Return — maximize/restore pane
• Ctrl-Shift-P — command palette

Exit a shell with Ctrl-D. Closing a running hosted pane detaches it; closing an already-exited hosted pane removes its session record.

2. Enable local detachable sessions#

Run the session host as a user service (systemd on Linux, launchd on macOS):

mpmux-cli service install
mpmux --sessiond-socket "$XDG_RUNTIME_DIR/mpmux-sessiond.sock" \
  --create-session --session-label shell

Inspect the daemon:

mpmux-cli service status

This default is local-only and relies on Unix socket permissions.

3. Let paired devices in over Iroh#

Switch on device authentication and the Iroh listener:

mpmux-cli service install --remote --restart
sudo loginctl enable-linger "$USER"   # Linux: keep it running when you log out

Without --remote, mpmux-cli pair fails with auth-unavailable. --remote creates the admin token ~/.config/mpmux/sessiond-admin-token (it lets you create invites and manage devices, and never leaves this machine), writes the service and starts it. --restart applies the change to a service that already runs; it ends the host's shells. Devices on the same network connect directly, others through the relay relay.mightypainting.dev; --relay-only always uses the relay. Terminal traffic and pairing over Iroh are encrypted: the relay sees connection metadata, not terminal text. Guide chapter 8 has the whole setup, a server without a display, and a Mac; your own relay server replaces the default relay.

4. Pair Android#

With the desktop client still running, create a one-time QR in another terminal:

mpmux-cli pair qr-code \
  --device-label "Android tablet" \
  --output /tmp/mpmux-android-pair.png

Open the Android app's session-host setup, choose QR pairing, and scan the image. The invite expires and is usable once. It contains no admin token or long-lived device token. Android receives its device token once and stores the paired-host profile privately.

Short-code alternative:

umask 077
mpmux-cli pair short-code \
  --device-label "Android tablet" \
  --code-output-file /tmp/mpmux-pair.code

Enter the code in Android's short-code pairing flow, then trash the code file. Do not paste invites, codes, endpoint ids, or tokens into chat, screenshots, or bug reports.

5. Use the tablet#

After pairing, Android lists or restores the hosted workspace. Hardware Ctrl-C, Ctrl-D, and other terminal control keys are forwarded to the PTY. The on-screen keyboard, pane focus, tabs, splits, reconnect, Kitty graphics, file upload, and voice input are client-side interactions; durable terminal state remains on sessiond.

If Android sleeps or changes networks, allow it to reconnect and request a fresh snapshot. Do not delete the host session merely because a mobile client briefly disconnects.

6. Move a workspace between devices#

One interactive client controls a hosted workspace at a time. To move it, use the explicit Take Over action on the device that should own it (Android picker, desktop command palette, or the startup prompt). There is no confirmation dialog and no approval is needed on the source device.

While a transfer is in progress the chrome shows Taking over workspace…, then Restoring workspace…, and only becomes Connected here once the pane streams are ready. If the destination cannot reach the host after the transfer, the workspace is owned but offline, and that state is reported rather than hidden.

The former owner shows Active on another device and stops accepting input; it does not reclaim automatically when it reconnects. It keeps the last frame it received, so its panes stay frozen at that point: there is no read-only live view. Every pane also shows a View only · has control · take over to interact badge so a frozen pane is not mistaken for a broken one. Use the explicit Take Over action on the device that should own the workspace to make it interactive again.

A restore can also be partial: a pane whose session attaches but has no snapshot yet is reported as session restore incomplete: N of M panes have no snapshot (<sessions>), and the affected tab shows why it is not ready instead of presenting an empty pane.

If the host does not support the ownership contract, the action fails with a clear message instead of detaching the current owner. Move a workspace with mpmux-cli session takeover-status to inspect ownership and mpmux-cli session takeover to take over from automation. See docs/SESSION_ATTACH_PROTOCOL.md section 14 and docs/HANDOVER_VALIDATION.md.

Ownership is bound to the client instance that claimed it, not just to a device token or local account. A mpmux-cli session takeover therefore leaves the workspace owned by that CLI process, so a later GUI session must Take Over explicitly before it can interact. The same applies between two GUI instances.

Direct LAN alternative#

Direct TCP with an auth store is authenticated plaintext: keystrokes, terminal output, pairing data, and device credentials are not encrypted on the wire. Use it only on a trusted private network, preferably behind WireGuard or another encrypted tunnel. The daemon deliberately rejects non-loopback binds unless --tcp-allow-non-loopback is supplied.

Before diagnosing mpmux, verify that the tablet can route to the host. Guest Wi-Fi and AP/client isolation commonly allow internet access while blocking tablet to host traffic. See docs/TROUBLESHOOTING.md and docs/SESSION_REMOTE_SECURITY.md.