Connecting on Apple TV
Add hosts, choose between password and Secure Enclave key authentication, and use Mosh from tvOS.
The host editor
vmuxTV stores its servers as saved hosts. To open the host editor, focus the Hosts tab and press the + button in the top-right corner. To edit an existing host, long-press its row in the list and choose Edit from the context menu.
The editor is a Form view with three sections — Destination, Authentication, and Transport — plus a validation message panel that appears at the bottom if a required field is missing or invalid.
Destination fields
| Field | Description | Default |
|---|---|---|
| Label | Friendly name shown in the host list. Optional. | empty |
| Host | Hostname or IP address (for example prod.example.com or 10.0.1.4). Required. | empty |
| Port | TCP port for the underlying SSH connection. Must be 1 – 65535. | 22 |
| Username | Remote username. Required. | empty |
| TERM | Value of the TERM environment variable advertised to the remote. | xterm-256color |
The Label is what appears as the headline in the host list. If you leave it empty, the host's username@host:port string is used instead.
Authentication
vmuxTV supports two authentication methods. Pick one in the Method picker:
| Method | Description |
|---|---|
| Password | Type a password into the Secure Field below the picker. The password is stored in the system Keychain on this Apple TV and never written to disk in plaintext. |
| Secure Enclave key | vmuxTV signs authentication challenges with a P-256 key generated inside this Apple TV's Secure Enclave. The private key cannot be exported. The public key must be installed in ~/.ssh/authorized_keys on the remote host. |
If you change the Method for an existing host to Secure Enclave key, the password field disappears and a footnote reminds you that vmuxTV will use the on-device key. The previously stored password remains in the Keychain and can be restored by switching the method back to Password.
Where to find the Secure Enclave public key
vmuxTV does not currently include a UI for exporting the public key from the Apple TV. The simplest workflow is:
- Set up the same host on vmuxPhone or vmuxMac and use the SSH Key Manager there.
- Or, on the Apple TV, save the host with Password authentication first, log in once, append your existing public key to
authorized_keys, then edit the host and switch to Secure Enclave key.
For the deeper picture of how vmux handles SSH keys across the family, see Authentication Methods.
Transport
| Transport | Notes |
|---|---|
| SSH | Plain SSH session with a PTY. The most common choice. |
| Mosh | UDP-based roaming protocol. Good if your home network is flaky and you want the session to survive a brief Wi-Fi hiccup. |
| vmux | Connects through the vmux multiplexer if your remote runs vmuxd. Most users will not need this. |
| tmux | Connects through tmux -CC control mode. Niche; included for parity with the rest of the vmux family. |
| Telnet | Plain Telnet. Useful only for embedded devices that still expose Telnet. No encryption. |
| ET | Eternal Terminal. Niche. |
Mosh on tvOS
When you choose Mosh, four extra fields appear:
| Field | Description | Default |
|---|---|---|
| mosh-server command | Path or command name for the remote mosh-server binary. | mosh-server |
| UDP port or range | Single port (60001) or range (60001:60010) for the UDP session. Leave blank to let mosh-server pick. | empty |
| Prediction | Local prediction mode. Adaptive is the right answer almost always. | adaptive |
| Address Family | prefer-inet (IPv4 first), prefer-inet6, or inet/inet6 only. | prefer-inet |
Mosh on Apple TV works the same way Mosh works everywhere else: the SSH side starts the mosh-server process on the remote, then a UDP session takes over. The TV must be able to reach the remote on the chosen UDP port. On a typical home network with NAT, the outbound UDP path is fine; on more locked-down networks, ask your network admin to allow outbound UDP to the configured port range.
For a deeper Mosh primer, see Mosh Connections.
Saving and connecting
Press Save to validate the form and store the host. The validation panel surfaces these errors:
- "Host is required." — the Host field is empty.
- "Username is required." — the Username field is empty.
- "Enter a valid TCP port." — Port is not a number in 1 – 65535.
- "Password is required for password authentication." — Method is Password but the field is blank.
- "TERM is required." — the TERM field was cleared and never refilled.
After Save, the editor closes and the host appears in the list. Select the row to open a new session and jump to the Sessions tab.
Connection lifecycle
Every session has one of four states. The colored dot in the status bar at the top of the terminal reflects the current state:
| Color | State | Meaning |
|---|---|---|
| Orange | connecting | Authentication or transport handshake in progress. |
| Green | connected | The PTY is open and the shell is live. |
| Gray | disconnected | The session ended cleanly. |
| Red | failed | The connection attempt failed. The status bar shows the error message. |
When a session is connecting, the bar reads Connecting to user@host:port.... Failed connections leave the error in place — for example, Authentication failed, Connection refused, or Operation timed out.
The connection attempt times out after about 15 seconds if the remote is unreachable. Mosh sessions roam silently in the background; SSH sessions drop on network change and need a manual reconnect.
Reconnecting
If a session disconnects:
- Focus the Hosts tab.
- Open the same host again — vmuxTV creates a fresh session.
There is no Reconnect button on the disconnected session itself in vmuxTV; the simplest path back is opening the host from the list. Saved profiles and stored passwords mean reconnecting takes one click.
If you want a session that survives network blips without manual reconnection, save the host with Mosh as the transport.
Closing a session
Open the Settings tab. Under Sessions, long-press a session row and choose Close. The session disconnects and disappears.
You can also let sessions close themselves — when the remote shell exits (exit, Ctrl+D, server-side kill), the session moves to the disconnected state but stays in the list until you close it from Settings.
Multiple sessions at once
vmuxTV supports more than one open session at a time. To switch between them:
- From the terminal — press the Menu/Back button on the Siri Remote (the button that closes apps elsewhere). This cycles to the next session in the list.
- From the Settings tab — every open session is listed under Sessions with its host's destination and a status dot.
A small set of dots near the bottom of the terminal screen indicates how many sessions are open and which one is active. The status bar at the top right shows n/total (for example 2/3).
Related
- Authentication Methods — full breakdown of password, Secure Enclave, agent, and remote signer flows.
- SSH Connections — what vmux sets in the remote environment.
- Mosh Connections — the Mosh primer.
- Input — Remote and Gamepad — what every button does inside a session.
- Troubleshooting — for connection failures and timeouts.