Getting started
Install vmuxMac, open your first window, and walk through a complete first-use flow.
Install vmuxMac
vmuxMac is distributed through the Mac App Store. Search for vmuxMac in the App Store and install it the same way you install any other Mac app. Direct download builds, when offered, are notarized for Gatekeeper, so the first launch will go through the standard "downloaded from the internet" prompt and then never ask again.
vmuxMac is sandboxed. The first time you connect to a remote host, macOS may ask whether the app is allowed to make outgoing network connections. Approve the prompt to enable SSH and Mosh.
First launch
Open vmuxMac from Launchpad, Spotlight, or your Applications folder. You will see a single terminal window sized roughly nine hundred by six hundred pixels, with a black background and the title vmux. The window starts a local shell using your login shell — whatever SHELL is set to in your environment, falling back to your account's shell from /etc/passwd, then /bin/zsh. The shell launches as a login shell so your .zprofile, .bash_profile, or fish login config runs as expected.
You should see your normal prompt and any login banner from your shell. If your prompt looks different from your usual Terminal.app or Ghostty prompt, see Themes and fonts and Connecting for environment differences.
A complete first-use flow
The shortest path to having vmuxMac feel like home is the five-minute flow below. Each step has the keyboard shortcut so you can keep your hands on the keyboard.
1. Open a second window
Press Cmd+N. A second window opens with another local shell. The two windows are independent — closing one does not affect the other.
If you would rather have a tab inside the current window, press Cmd+T. Tabs and windows behave the same way internally; the tab variant is here so you can use macOS's built-in tab behaviors. See Windows and tabs for the full model.
2. Run a local command
Type a familiar shell command:
ls -la ~You should see your home directory listing with colors from your shell's default theme. Try:
echo "$SHELL"The output is the shell vmuxMac launched. If it is not the one you wanted, change SHELL in your login items or in System Settings → Users and Groups → Login shell.
3. Open the command palette
Press Cmd+Shift+P. A floating palette appears in the center of the window. Start typing zoom in and select the matching command. The terminal text gets larger by one point. Reset it with Cmd+0 or by running Reset Zoom in the palette.
The palette contains every action vmuxMac can perform. See Command palette for the full list.
4. Open Settings
Press Cmd+,. The macOS Settings window opens with four tabs: General, Appearance, CRT, and Mac. Switch to the Mac tab and try toggling Hidden Title Bar. The title bar in your other windows hides immediately. Toggle it back on if you prefer the standard chrome.
Every change you make in Settings is saved automatically. You do not need to click an Apply button. See Settings for a walkthrough of every option.
5. Connect to a remote host
In any terminal window, type:
ssh user@example.comThe local shell launches the system ssh binary, which uses your existing ~/.ssh/config and ~/.ssh/known_hosts exactly the way Terminal.app or any other Mac terminal would. If you prefer to use vmuxMac's own connection UI and saved-host store, see Connecting.
6. Quit cleanly
When you are done, press Cmd+Q to quit, or close the last window with Cmd+W. vmuxMac does not restore windows on next launch — each launch starts you with a single fresh window.
If a window has an active SSH or Mosh session, closing it disconnects that session.
Default keyboard shortcuts
The following shortcuts work out of the box. Most can be rebound — see Command palette for the full list and how to remap them.
| Shortcut | Action |
|---|---|
| Cmd+N | New window |
| Cmd+T | New tab |
| Cmd+W | Close current window or tab |
| Cmd+Q | Quit vmuxMac |
| Cmd+, | Open Settings |
| Cmd+Shift+P | Toggle command palette |
| Cmd+Shift+R | Toggle CRT effect |
| Cmd+K | Clear scrollback |
| Cmd++ | Zoom in (font size) |
| Cmd+- | Zoom out (font size) |
| Cmd+0 | Reset zoom |
| Cmd+C | Copy selection |
| Cmd+V | Paste |
A note on local shells
vmuxMac launches a real interactive login shell, not a sandboxed minimal shell. That means your shell can call any binary your account has access to: git, brew, node, python, anything in PATH. The default PATH includes /opt/homebrew/bin, /usr/local/bin, and the standard system paths.
Environment variables vmuxMac sets explicitly:
| Variable | Default | Why |
|---|---|---|
TERM | xterm-ghostty | Tells your remote tools that the terminal supports Ghostty's full feature set. |
TERM_PROGRAM | ghostty | Identifies the terminal engine to programs that care. |
COLORTERM | truecolor | Advertises 24-bit color so modern apps render their full palette. |
SHELL | Your login shell | Used by tmux and other tools that ask which shell to spawn. |
HOME, USER, LOGNAME | From your account | Standard Unix expectations. |
PATH | Your existing PATH if set, otherwise /opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin | Mirrors a normal login shell. |
If a tool on your remote host does not understand xterm-ghostty, set TERM=xterm-256color either in your remote shell's startup file or via TERM=xterm-256color ssh user@host.
Where to go next
- Connecting — SSH, Mosh, saved hosts.
- Windows and tabs — the macOS window model in vmux.
- Settings — every option, every tab.
- Troubleshooting — common first-launch problems.