SSH Connections
Connect to remote hosts over SSH.
Connecting to a Host
When you open a new window, you'll see a connection form. Fill in:
| Field | Description | Default |
|---|---|---|
| Host | Hostname or IP address | — |
| Port | SSH port | 22 |
| Username | Your remote username | — |
| Password | Password (leave blank to use key) | empty |
Tap Connect to start the session. vmux establishes an encrypted SSH connection and opens an interactive shell on the remote host.
Authentication
vmux supports four authentication methods: password, Secure Enclave device key, SSH agent bridging, and companion app signing. You choose the method per host in the connection form.
See Authentication Methods for a full guide to each method, identity management, and setup instructions.
Terminal Environment
vmux sets the following environment variables on the remote host:
| Variable | Value | Notes |
|---|---|---|
TERM | xterm-256color | Standard 256-color terminal type |
COLORTERM | truecolor | Advertises 24-bit color support; toggleable in settings |
LANG | en_US.UTF-8 | UTF-8 locale |
TERM_PROGRAM | vmux | Identifies vmux to remote tools |
TERM_PROGRAM_VERSION | (app version) | Current vmux version |
If your remote tools don't handle truecolor well, you can disable the COLORTERM variable in Settings.
Credential Storage
Passwords are stored in the system Keychain on your device. They're never written to disk in plain text. When you save a host profile, the password is kept in the Keychain and used automatically on reconnection.
Secure Enclave keys never leave the device hardware — they can't be exported or copied.
Reconnecting
If your session disconnects, vmux shows a disconnected overlay with a Reconnect button. Tap it to reconnect using the same profile.
vmux restores the pane snapshot on each connect attempt, so your previous terminal state stays visible while the connection comes back.
The connection times out after 15 seconds if the remote host is unreachable.
Unstable Networks
SSH connections drop when your network changes or goes through a brief interruption. If you're on a flaky connection, consider using Mosh instead — it roams across networks and handles intermittent connectivity gracefully.