vmux Daemon (CLI)

What it is

vmux ships as two CLI binaries that together give you a tmux-style multiplexer:

• vmuxd is the persistent server. It owns PTYs, sessions, tabs, and panes. It listens on a Unix domain socket and never draws to your terminal.
• vmux is the client. It connects to the daemon's socket, attaches your real terminal to a session, forwards keystrokes, and renders frames the daemon sends back.

You launch vmuxd once and leave it running. From any number of shells you run vmux attach, work for a while, detach with Ctrl+D (closing stdin) or kill -HUP, reattach later from a different shell, and pick up exactly where you left off. Closing the terminal that owns a vmux client never kills the work inside the session — only the daemon does that.

Why use it instead of tmux

vmux is the same piece of software that powers the visionOS, Mac, and iOS apps in the rest of the vmux family. The CLI exposes the same daemon those apps drive, so:

• A session you start in a terminal can be attached from the visionOS app on the same machine (and vice versa).
• Pane state, runtime status, exit codes, and teammate metadata are first-class. vmux state returns a structured JSON snapshot suitable for scripts, dashboards, or AI agents.
• Panes can run any process — not just a shell. vmux pane launch accepts an explicit argv, cwd, and environment, and the daemon tracks process lifecycle separately from PTY state. vmux wait-pane-exit blocks until that process terminates and exits with its exit code.

This makes vmux a useful building block for orchestrating long-running CLI workloads (agents, builds, CI shells) where you need to drop in interactively, walk away, and rejoin later — and where you need to script those operations without scraping tmux list-panes -F.

How the pieces fit

vmux attach        ┐
vmux pane launch   │  ──── Unix socket ────►  vmuxd
vmux state         │     (length-prefixed       │
vmux ls            │      JSON frames)          │  owns:
                   ┘                            │   - sessions
                                                │   - tabs
                                                │   - panes (each with its own PTY)
                                                │   - process lifecycle

The wire format is JSON messages prefixed with a 4-byte big-endian length. The protocol is internal — you never speak it directly; you use vmux or one of the GUI apps.

Object model

The active concept is the pane. vmux attach connects you to a session and your keystrokes go to whichever pane the daemon currently considers active.

Default paths

The socket is per-UID, so two users on the same Mac get independent daemons without configuration.

Auto-start

If you run vmux and the socket is missing or the connection is refused, the client will spawn vmuxd --daemonize automatically using the sibling binary it can find. You only need to start vmuxd manually when you want to override flags, run it in the foreground for debugging, or pin it to a non-default socket.

This means a fresh shell can simply do:

vmux attach

…and the daemon will come up on first call.

System requirements

vmux uses the same VMuxProtocol wire layer as the visionOS app, so the same daemon process can serve a CLI client and a Vision Pro window at the same time.

Where to go next

• Installation — building the binaries and installing them on your PATH.
• vmuxd reference — flags, signal handling, and daemonization.
• vmux attach — attaching, detaching, and multi-client mirroring.
• Sessions — ls, session create.
• Panes — pane create, pane launch, pane signal, pane close, wait-pane-exit, state.
• Configuration file — every key.
• Shell integration — wiring vmux into ~/.zshrc and your prompt.
• Troubleshooting — what to do when things go wrong.

See also

• Built-in shell (vsh) — vmux's local command shell, also drives panes inside the GUI apps.
• SSH connections — pointing a pane at a remote host instead of a local shell.
• All vmux apps — the full family of clients that talk to the same daemon.