Built-in shell (vsh) on Mac

Experimental — vsh is under active development. Commands, syntax, and behavior may change between releases. Use the full vsh manual for the canonical reference.

What vsh is on Mac

vsh is vmux's built-in shell. It is the same shell on every vmux platform: a small typed command surface that controls vmux itself — connections, panes, themes, fonts, settings — without leaving the keyboard. On Mac, vsh sits next to the regular login shell that ships with macOS. You can use either, and you can flip between them.

Most of the visionOS vsh commands work on Mac. The ones that do not are spatial-only (VKeyboard, glass background, immersive controls); the full reference at Built-in Shell (vsh) is the source of truth and notes which commands are platform-specific.

Activating vsh

There are two ways to type vsh commands on Mac:

• Standalone — open the command palette with Cmd+Shift+P and run vsh (or whatever you have rebound it to). A shell prompt opens inside the current window. Type vsh commands, press Return, see the result. Press Esc to leave.
• Inline during a managed session — when a vmux managed SSH or Mosh session is active, prefix any command with ! to run it through vsh instead of the remote shell. For example, while connected to a server, typing !themes lists available themes; !set-font-size 16 resizes the font.

Tab completion is available for command names and arguments. Press Tab after a partial command to complete it; press Tab again to cycle through alternatives.

A Mac-specific quick start

A typical first vsh session looks like this:

> help
> connect
> ssh user@example.com
> theme
> font
> ghostty-import
> set-titlebar toggle
> set-padding 10

• help lists every command grouped by category. Pass a name (help ssh) for usage details.
• connect opens the connection form for managed sessions.
• ssh user@host starts a managed SSH session in the current window.
• theme switches themes; the bare command lists them.
• font switches fonts; the bare command lists them.
• ghostty-import reads your Ghostty config and applies the recognized settings. See Themes and fonts for the key map.
• set-titlebar toggle flips the hidden-title-bar setting.
• set-padding 10 sets window padding to 10 pixels.

Quick command reference (Mac-relevant)

This is a subset of the full vsh reference, filtered to commands that have a meaningful effect on the Mac app. See the full vsh manual for everything else.

Connection

Settings (macOS-applicable)

Theme and font

Window and tab

Files and system

Migration

Settings commands without arguments

Settings commands print the current value when run without arguments. For example:

• set-opacity prints the current background opacity.
• set-font-size prints the current font size in points.
• set-titlebar prints whether the title bar is hidden.

This makes vsh a quick way to inspect state from the keyboard without opening Settings.

How vsh fits with the local Mac shell

Every new vmuxMac window starts a regular interactive login shell — your usual zsh or bash or fish. vsh is something you launch on top of that, not a replacement for it. The two never share state: vsh has its own command surface and does not see your shell's variables, aliases, or functions, and your shell does not see vsh's commands.

If you find yourself running vsh commands often, bind your favorites to keyboard shortcuts (see Command palette → Keybindable column) so the most common actions are one keystroke.

Where to go next

• Built-in shell (vsh) — the full vsh reference shared across vmux apps.
• Command palette — the GUI equivalent of typing in vsh.
• Themes and fonts — theme, font, and ghostty-import in context.
• Connecting — when to use ssh in vsh vs the local shell.