Connecting

The connection form

Every connection on vmuxPhone is described by a saved host. You build one in the New Host or Edit Host form, which opens from the + button on the host list or the Edit swipe action.

The form is divided into four sections: Destination, Authentication, Transport, and (when the transport is tmux) Tmux. The fields you see in each section change based on the transport you pick.

Destination

Field	Meaning
Label	A friendly name shown in the host list and on widgets. Optional.
Host	DNS name or IP address. Bonjour names like `mac-mini.local` work once you grant Local Network access.
Port	TCP port. Default `22` for SSH, also used as the SSH bootstrap port for Mosh.
Username	Remote login name.
TERM	The `TERM` environment variable sent to the remote shell. Default `xterm-256color`.

Authentication

vmuxPhone supports two methods on iPhone today: Password and Device Key.

Method	Where the secret lives	Notes
Password	iOS Keychain on this iPhone	Saved alongside the host. Re-used automatically on reconnect.
Device Key	Secure Enclave on this iPhone	Hardware-backed P-256 key. Cannot be exported or copied. Approved with Face ID.

To use Device Key auth you also have to put the matching public key on the server. See SSH key manager for how to copy the public key to the clipboard, then paste it into ~/.ssh/authorized_keys on the host. The first connection after that asks for Face ID and connects without a password.

If you use vmuxAgent on a paired Mac with RemoteSignerPhone, that flow does not apply on vmuxPhone — the agent flow is for SSH clients on the Mac, not for the iPhone terminal app itself. vmuxPhone signs locally with its own Secure Enclave key.

Transport

A segmented picker exposes the available backends.

Transport	Notes
SSH	Default. Single-pane interactive shell over a TCP SSH session.
Mosh	UDP-based protocol that survives network changes and sleep. Requires `mosh-server` on the remote. Extra Mosh options appear when picked.
vmux	Connect through a running `vmuxd` daemon to attach to multiplexed tabs and panes. The phone shows a breadcrumb bar with tabs and panes when the daemon emits structured scene updates.
Telnet	Plaintext Telnet. Use only on a trusted network.
ET	Eternal Terminal. Drop-in SSH alternative that reconnects automatically.
tmux	Hidden behind a feature flag in this release. The tmux row only appears in builds where `FeatureFlag.tmuxBackend` is on.

When you pick Mosh, four additional fields appear:

Field	Default	Notes
mosh-server command	`mosh-server`	Path or name of the binary on the remote host. Override only if you installed it somewhere unusual.
UDP port or range	empty	A port like `60000` or a range like `60000:60010`. Leave empty to let the server pick.
Prediction	Adaptive	Local echo mode. Always shows predictions immediately; Never disables them; Adaptive shows them only on slow links.
Address Family	Prefer IPv4	IPv4-first, IPv6-first, IPv4-only, IPv6-only, all, or auto.

When you pick tmux (in builds where it is enabled), a fifth section appears with Session Name plus an Advanced disclosure for an alternate tmux binary path and extra arguments.

Authentication on iPhone

Below is the practical guide. The general identity and key model is the same as on visionOS — see SSH connections and Authentication methods for the full reference.

Password

Type the password into the form and tap Save. iOS Keychain stores it on this device only and never syncs it. If you forget the password you can re-enter it from the Edit Host screen — vmuxPhone shows the existing field empty and accepts a new value.

Device key (Secure Enclave)

The first time you set up Device Key auth:

Open the host list, then tap Security → Device Key.
Tap Generate Device Key. iOS provisions a P-256 key inside the Secure Enclave.
Tap Copy Public Key.
Paste the line into ~/.ssh/authorized_keys on the server. Make sure the file has mode 0600 and that the directory has mode 0700.
Edit the host on vmuxPhone and switch Method to Device Key. Save.

When you connect, iOS asks for Face ID once per signing challenge. The private key never leaves the Secure Enclave hardware.

If you delete the device key from the manager, every host configured to use it has to be re-authorized after you generate a new one — the public key changes.

Agent forwarding

vmuxPhone does not forward an upstream SSH agent into the remote session. The Secure Enclave key stays bound to the iPhone and is only used to authenticate the connection itself. If you need agent-style behavior on the remote (so that a Git command on the server can push using your local key), use a remote agent like vmuxAgent on a Mac, or set up ssh-agent forwarding on the server side using your own credentials.

Companion app signing

If you also run RemoteSignerPhone, it operates independently of vmuxPhone. vmuxPhone uses its own Secure Enclave key. Two iPhones in the same household can hold separate signing keys without affecting each other.

Reconnecting

Sessions stay live as long as the app is in the foreground or in the iOS background grace window. When something interrupts the connection, vmuxPhone surfaces it on the status line and tries to recover automatically.

Status line	What happened	What you can do
*Connecting to destination…*	First handshake or reconnect in progress.	Wait. Authentication takes a few seconds.
Maintaining connection in background…	App is in the background; iOS grace timer is running.	Bring vmuxPhone forward to keep it alive.
Session paused in background.	Grace timer ran out and the OS suspended the connection.	Foreground the app — vmuxPhone reconnects automatically.
Reconnecting…	Network change or background return; vmuxPhone is re-establishing.	Wait. If it does not finish in 15 s, tap the menu and pick Reconnect.
Connection failed: reason	The remote refused or the network broke.	Tap the menu, pick Reconnect, or fix the underlying problem.

The session menu (the round button in the top-right of the terminal) has explicit Disconnect and Reconnect entries. Reconnect disconnects, waits about 150 ms, and connects again with the same profile.

Terminal environment

vmuxPhone sets the same environment variables on the remote shell as the visionOS app:

Variable	Value	Notes
`TERM`	The TERM value from the host form	Defaults to `xterm-256color`.
`COLORTERM`	`truecolor`	Toggleable in Appearance. Disable if a remote tool mishandles 24-bit color.
`LANG`	`en_US.UTF-8`	UTF-8 locale.
`TERM_PROGRAM`	`vmux`	Lets remote tools detect vmux.
`TERM_PROGRAM_VERSION`	App version	Useful in bug reports.

Saved hosts and the Keychain

Each saved host is a record in UserDefaults plus, optionally, a Keychain entry holding the password. Deleting a host deletes both. Backups taken through iCloud or a Mac restore the host metadata but not the Keychain — passwords have to be re-entered after a restore. Secure Enclave keys do not transfer at all; you generate a new one and re-authorize on the server.

The host list is local to this iPhone in this release. There is no automatic sync across vmuxPhone and vmux on Vision Pro or vmuxMac yet — the import / export flow is the manual workaround.

SSH connections — protocol-level reference.
Mosh on iPhone — backgrounding behavior and reconnect.
SSH key manager — generate, copy, and delete the device key.
Workspace — multi-window navigation once you are connected.

Connecting

On this page