vmux
AppsvmuxTV

Getting Started on Apple TV

Install vmuxTV on Apple TV, learn the three-tab layout, and connect to your first server.

Install vmuxTV

vmuxTV is distributed through the Apple TV App Store. Two ways to install it:

  1. From the Apple TV. Open the App Store on your Apple TV, search for vmux, choose vmux for Apple TV, and select Get or Install.
  2. From your iPhone or Mac. If you bought vmux on another Apple device that shares your iCloud account, the tvOS version appears under Purchased in the App Store on Apple TV. Select Cloud to install.

The app downloads in the background. When it finishes, vmuxTV appears on the Apple TV Home Screen alongside your other apps.

vmuxTV requires tvOS 17 or later and runs on any Apple TV 4K. The original Apple TV HD is not officially supported because the GPU does not have enough memory for the renderer's glyph atlas at television-scale font sizes.

Launch the app

Select the vmux icon on the Home Screen with the Siri Remote. The app opens to the Hosts tab on first launch because there is nothing else to show — no saved hosts, no active sessions.

If this is the first time you have ever launched vmuxTV, you will see a blank list with a No Hosts Yet placeholder. That is the expected starting state.

The three-tab layout

vmuxTV is built around a tab bar at the top of the screen. The Siri Remote moves focus between tabs by swiping left and right on the clickpad or pressing the directional edges.

Sessions tab

The Sessions tab is where active terminal sessions live. When you connect to a host, this tab becomes the active view automatically and the terminal fills the screen.

If no sessions are open, the Sessions tab shows a No Active Sessions placeholder pointing you to the Hosts tab.

Hosts tab

The Hosts tab is the saved-server list. From here you can:

  • Add a new host with the + button in the top-right of the navigation bar.
  • Open a saved host by selecting its row — vmuxTV opens a session and switches to the Sessions tab automatically.
  • Edit or delete a host by long-pressing on the clickpad to open the context menu.

Each host row shows a label (or the hostname if no label is set), the SSH or Mosh destination, and a subtitle that summarizes transport and authentication.

Settings tab

The Settings tab holds:

  • Theme picker — pick from the bundled dark and light themes.
  • Font size — increase or decrease the terminal font size for the active session. Range is 20 pt to 48 pt.
  • Sessions list — every open session, with a status indicator and a long-press Close action.

There is no command palette and no keyboard shortcut editor. Everything user-configurable lives here.

Add your first host

  1. Focus the Hosts tab.
  2. Press the + button in the top-right.
  3. The host editor opens. Fill in:
    • Label — optional friendly name shown in the host list.
    • Host — hostname or IP address (for example prod.example.com).
    • Port — defaults to 22.
    • Username — your remote login.
    • TERM — defaults to xterm-256color. Leave it alone unless your remote tools require something else.
  4. In the Authentication section, choose:
    • Password — type the password into the Secure Field. The Apple TV will offer to use the iPhone Keyboard for faster entry.
    • Secure Enclave key — vmuxTV will use the SSH key bound to this Apple TV's Secure Enclave. The public key for that device must already be in ~/.ssh/authorized_keys on the remote. See Connecting for how to fetch the public key the first time.
  5. In the Transport section, choose SSH for a standard shell or Mosh for the roaming protocol. Other transports (vmux, tmux, Telnet, ET) are listed for parity with the rest of the vmux family but are typically not used on Apple TV.
  6. Press Save.

The new host appears in the list. Selecting it opens a session.

Connect to your first session

With at least one saved host:

  1. Focus the host row in the Hosts tab.
  2. Press the clickpad. vmuxTV opens a session and switches to the Sessions tab.
  3. The status bar at the top of the terminal shows a colored dot:
    • Orange — connecting.
    • Green — connected.
    • Red — failed.
    • Gray — disconnected.
  4. When the dot turns green, the remote shell is live.

You will not see a command prompt until the remote shell finishes its login sequence — for hosts with motd banners or shell init that takes a moment, the screen stays mostly blank for a second or two.

Send your first command

Apple TV does not have a keyboard built in. To send text:

  • Press the Play/Pause button on the Siri Remote. The dictation bar slides up from the bottom of the screen. Type a command using the on-screen keyboard, dictate it with the microphone button, or use the iPhone Keyboard banner that appears on a paired iPhone.
  • Press Send or hit return. The command is sent to the remote shell.

For details on the dictation bar, see Voice Dictation. For everything the Siri Remote and paired controllers can do, see Input — Remote and Gamepad.

Where to go next

vmuxTV

A native Apple TV terminal for monitoring servers and running remote sessions on the big screen.

Connecting on Apple TV

Add hosts, choose between password and Secure Enclave key authentication, and use Mosh from tvOS.

On this page

Install vmuxTVLaunch the appThe three-tab layoutSessions tabHosts tabSettings tabAdd your first hostConnect to your first sessionSend your first commandWhere to go next