Muxie Get Muxie
Concepts Explanation

Durable sessions

How Muxie keeps terminals alive across closed windows, restarts, and dropped connections — the daemon, the holder, replay, and reattach.

A normal terminal session is owned by its window. Close the window, lose the SSH connection, or restart the app and the shell — and everything running in it — dies. For long-running coding agents and remote work, that’s the wrong default. Muxie makes sessions durable: they outlive the window and the connection.

The daemon owns your terminals

Muxie runs terminal sessions through a small bundled background process, the daemon (muxied). The app window is just a viewer attached to it. When you type, the keystroke is relayed through the daemon to the real PTY; when a program prints output, the daemon streams it back to the window.

Because the PTY lives in the daemon and not the window, closing the window doesn’t end the session. Reopen Muxie and it reattaches to the same session, with scrollback intact.

Holder and router

The daemon is split into two parts so that upgrading Muxie doesn’t kill your work:

  • The holder owns the actual PTYs. It’s a stable, version-independent singleton: every app version resolves to the same holder, and relaunching the app reuses the one already running.
  • The router (or front) is the upgradeable piece that talks to the app. When you update Muxie, only the router restarts; the holder — and your running sessions and scrollback — carry on untouched.

You don’t manage these directly. They start on demand and clean themselves up; this section just explains why an app update no longer drops you into a fresh shell.

Replay: scrollback that comes back

When you reattach, Muxie doesn’t show you an empty screen. The daemon keeps a server-side model of each terminal’s screen and scrollback, and replays it on reattach — including colors and cursor position — so the pane looks exactly as you left it.

Remote sessions reconnect

Durability isn’t only about local sessions. For SSH and sprites.dev sessions, the remote process keeps running on the host. If the transport drops (a network blip, a closed laptop), Muxie detects it and auto-reconnects with backoff, then replays the screen. If reconnection ultimately fails, the local pane exits — but the work on the host is still there to reattach to later.

Orphan sessions

Because sessions are durable, a crash or a clobbered window can occasionally leave a session running with nothing attached to it. Muxie can garbage-collect these orphans after a grace period (one hour by default), and you can recover or kill them by hand from the command palette (recover-orphan-sessions). The grace period is configurable — set orphanReapGraceMs to 0 to turn reaping off entirely. See Recover orphaned sessions.