Troubleshooting on Apple TV

Connection problems

"Operation timed out" when connecting

The Apple TV cannot reach the remote host within the 15-second timeout. Common causes:

• Wrong hostname or port. Open the Hosts tab, long-press the host, choose Edit, and verify Host and Port. For SSH the default is 22; for hosts behind a NAT or jump box it is something else.
• Firewall or NAT in the way. Many home routers block outbound traffic to non-standard SSH ports. Try connecting from another device on the same network (laptop or phone). If it fails there too, the problem is your network, not vmuxTV.
• Remote is asleep or down. Wake the remote and retry.
• DNS not resolving. Try the IP address directly. If the IP works but the hostname does not, the Apple TV is not getting DNS from your router. Settings → Network → Wi-Fi → your network → Configure DNS to set Google (8.8.8.8) or Cloudflare (1.1.1.1) DNS.

"Authentication failed"

The username, password, or key was rejected.

• For password auth — re-enter the password in the host editor. Use the iPhone Keyboard banner to avoid typos. If it still fails, log in from another device to confirm the password is right.
• For Secure Enclave key auth — vmuxTV signs with a key bound to this Apple TV's Secure Enclave. The corresponding public key must be in ~/.ssh/authorized_keys on the remote. If you have not added it yet, see Connecting for the workaround (use vmuxPhone or vmuxMac to install the key, or save the host with password auth first and add the key over that session).
• Check /var/log/auth.log (or journalctl -u sshd) on the remote. The reason for rejection is logged there and is much more specific than the client-side message.

"Connection refused"

A TCP connection got through, but nothing accepted it. Either:

• sshd is not running on the remote. SSH into it from another device and start the service.
• The port is right but the service is something else. Some hosts run SSH on a non-22 port — check Port in the host editor.

Mosh session disconnects after a few minutes

Mosh roams across networks but it does need outbound UDP to keep the session alive. On home networks where the router enforces strict NAT or short UDP timeouts, the Mosh session can stall.

• Switch the host's transport to SSH in the host editor and reconnect. SSH does not have this problem on a stable network.
• If Mosh is mandatory, set a UDP port or range in the host editor and ask your network admin to allow outbound UDP to that range with a generous timeout (5+ minutes).
• See Mosh Connections for the broader Mosh primer.

Connection works on iPhone but not Apple TV

Same iCloud account, same Wi-Fi, same credentials, but the Apple TV times out.

• Confirm the Apple TV is on the same SSID. A 5 GHz-only AP and a guest 2.4 GHz network can both be advertised by the same router under different names with different routing rules.
• Check tvOS network settings. Settings → Network shows the active SSID and the assigned IP. If the IP is in a different subnet from the iPhone, your router is segregating clients.
• Reboot the Apple TV. This clears DHCP leases and stale ARP entries that occasionally make a device unreachable until the lease renews.

Remote and controller issues

Siri Remote arrows do not work in the terminal

The terminal view must be focused for arrow keys to forward. If you are in Settings or the Hosts tab and try to scroll a previously focused terminal, nothing happens.

• Swipe to the Sessions tab.
• Click the center of the clickpad once to ensure focus has landed in the terminal.
• The arrow edges of the clickpad now scroll.

If arrows still do nothing, the active session may be in the disconnected state. Check the colored dot at the top of the screen and reconnect if it is gray or red.

Play/Pause does not open the dictation bar

Play/Pause only triggers the dictation bar from inside an active session. From the Hosts or Settings tabs, Play/Pause is unmapped and tvOS may handle it as an audio control.

If you press Play/Pause inside an active session and nothing happens:

• The session may have lost focus. Click the clickpad once and try again.
• A modal dialog (the host editor sheet, an alert) is on top of the session and consuming the press.
• The remote's battery is too low to send Bluetooth events reliably. Charge the Siri Remote.

Game controller buttons do nothing

• The controller is not paired. Settings → Remotes and Devices → Bluetooth on the Apple TV must show your controller as connected.
• The controller is paired but in a different mode. Some controllers have multiple Bluetooth profiles (Switch / iOS / Android). Put it in iOS / tvOS mode.
• The terminal view is not focused. Click the clickpad on the Siri Remote or press the controller's Menu button to grab focus first.
• A specific button is unbound. Defaults are documented in Input — Remote and Gamepad. To customize, edit keybinds on vmuxMac or vmuxPhone — the bindings carry over.

Remote feels laggy

• Bluetooth interference. Microwaves, baby monitors, and crowded 2.4 GHz networks slow Bluetooth. Move the Apple TV closer to the router or turn the microwave off.
• Apple TV is busy. Force-quit other apps from the App Switcher (double-tap the TV button on the second-generation Siri Remote, swipe up on the offending tile).
• Battery low. A nearly-flat Siri Remote sometimes drops events before reporting low battery. Charge it on a Lightning or USB-C cable.

Voice dictation issues

The microphone button is grayed out

vmuxTV needs two privacy permissions for dictation. If either is denied, the on-screen keyboard's microphone is disabled.

• Open tvOS Settings → Apps → vmux.
• Make sure both Microphone and Speech Recognition are turned on.
• Relaunch vmuxTV.

If the toggles are absent, you may have declined the original prompts so completely that tvOS no longer offers them. Delete and reinstall vmuxTV — re-installation triggers the prompts again on first dictation use. (Saved hosts and Keychain entries are preserved across reinstall as long as the iCloud account is the same.)

Dictation transcribes the wrong words

• Speak more slowly and in shorter phrases. Apple's recognizer prefers complete utterances over rapid fire.
• Use NATO phonetic for letters. "alpha bravo charlie" is much more reliable than "a b c".
• Switch to Prose Mode if you are dictating natural language — Command Mode parses keywords like "enter" and "escape" as keystrokes and may surprise you.
• Edit the transcript before pressing Send. The transcript appears in the dictation bar and can be corrected with the on-screen keyboard or the iPhone Keyboard.

Dictation cuts off after a few seconds

tvOS's voice recognizer has a short utterance limit. Dictate one phrase at a time, press Send, then press the microphone button again for the next phrase. There is no "long form" mode on tvOS.

App stability

vmuxTV crashes on launch

• Force-quit and relaunch. Double-tap the TV button on the Siri Remote to open the App Switcher; swipe up on vmux to dismiss it. Reopen from the Home Screen.
• Reboot the Apple TV. Hold the TV and Volume Down buttons for five seconds.
• Update tvOS. Old tvOS builds occasionally hit GPU bugs that affect the Metal renderer. Settings → System → Software Updates.
• Reinstall vmuxTV. From the App Store, find vmux, choose Delete, then reinstall. Hosts and Keychain entries are preserved across reinstall on the same iCloud account.

vmuxTV freezes mid-session

The renderer is pull-based and goes idle when nothing changes on screen. A truly frozen session usually means the underlying SSH/Mosh transport stalled.

• Press the Menu button to switch to another open session and back. The renderer redraws.
• Open Settings, long-press the affected session, choose Close, and reopen the host. This forces a fresh transport.

Audio plays even though no one set bell

vmuxTV does not currently produce audio of its own — no bell sound, no UI sounds, nothing. If you hear audio coming from vmuxTV, it is the remote shell's \a (bell) byte being interpreted by tvOS as a system alert. There is no toggle for this on tvOS yet; mute the remote shell's bell with set bell-style none (bash) or setopt no_beep (zsh) in your remote .bashrc / .zshrc.

Reporting bugs

vmuxTV does not have an in-app diagnostics export — that surface is missing on tvOS because there is no system clipboard for the JSON to land in. To report a bug:

1. Note the host configuration (transport, port, auth method) and what you did.
2. Note the tvOS version (Settings → System → About) and Apple TV model.
3. If the problem is reproducible on vmuxPhone or vmuxMac, gather a diagnostics export from there — most issues that affect Apple TV affect those apps too, and their export contains relevant client-side telemetry.
4. File the report through the app's listed support channel on the App Store page.

Related

• Connecting — host configuration and connection states.
• Input — Remote and Gamepad — the full button reference.
• Voice Dictation — Command Mode versus Prose Mode.
• Mosh Connections — the Mosh primer.
• Authentication Methods — Secure Enclave key flow.