Support

dotMux is a native SSH client for iPhone and iPad that turns remote tmux sessions into real iOS tabs and panes. This page answers the questions that come up most often.

Contact

Stuck on something not covered here, or found a bug? Email dotmux@dotpt.com. If it's a connection problem, attaching a Diagnostics export (see the last question below) helps a lot.

Frequently asked questions

How do I connect?

1. Tap Add Host on the host list.
2. Enter the hostname or IP, the port (22 by default), and the username you use to log in.
3. Under Credential, pick a stored credential, or tap Manage credentials… to add one — paste an ed25519 key, generate a Secure Enclave key on the device, or save a password. (You can also leave the credential as None and dotMux will ask for a password when you connect.)
4. Save the host, then tap it to connect.

If a host has no usable stored credential, dotMux prompts for a password at connect time. You can tick Save password in that prompt to remember it for next time — it's only saved after the login actually succeeds, so a wrong password is never stored.

What kinds of authentication are supported?

• ed25519 keys — import them by pasting the key text or picking the file from the Files app. Passphrase-protected keys are fine: dotMux asks for the passphrase once at import and never stores the passphrase itself.
• Secure Enclave keys (P-256) — generated on the device, non-exportable, and signed entirely inside the Secure Enclave. You add the printed public key to your server's authorized_keys. The private key never exists outside the enclave, even to dotMux.
• Passwords — saved in the Keychain behind Face ID, or typed in fresh at connect time. Password login uses SSH's standard password method only; servers set up for keyboard-interactive-only auth will reject every attempt even when the password is correct. Use a key on those hosts.

RSA keys are intentionally not supported. Modern OpenSSH (8.8 and later) disables the legacy ssh-rsa SHA-1 signature by default, and that's the only RSA signature the underlying SSH library can produce today. A stored RSA key would look usable but silently fail to authenticate, so dotMux rejects RSA at import rather than pretend it works. Use an ed25519 key or a Secure Enclave key instead.

What is tmux control mode, and do I need it?

tmux control mode is what makes dotMux feel native. dotMux speaks tmux's control-mode protocol (tmux -CC) directly and rebuilds your workspace as native iOS UI: each tmux window becomes a tab, and each pane becomes a native view — focused full-screen on iPhone (swipe, or tap a pane in the switcher, to move between them), true side-by-side splits on iPad. You switch windows and panes with a tap, the way any iOS app should work.

It's on by default (there's a per-host toggle in the Add/Edit Host form). When you connect, dotMux launches or re-attaches a tmux session and renders it natively. If the host doesn't have tmux installed, or control mode can't start for any reason, dotMux falls back gracefully to a plain terminal — you stay connected, just without the native tabs and panes.

My terminal came back blank after I switched apps

This is expected, and it fixes itself. iOS suspends or even kills backgrounded apps to save power — dotMux doesn't fight that. Your tmux session keeps running on the server, so when you return, dotMux re-attaches to it and rebuilds your tabs and panes exactly where they were. Long-running jobs you left running keep running.

When a pane comes back blank, it's because tmux only replays new output on re-attach, not a pane's existing screen. dotMux automatically nudges tmux to repaint each visible pane right after re-attaching, so the content reappears within a moment. If a pane stays blank, switching tabs or sending any keystroke forces a repaint.

(A plain SSH shell — control mode off — has no server-side session to re-attach to, so after a suspension it shows the disconnected state and you reconnect deliberately. That's by design: dotMux won't silently drop you into a different fresh shell.)

How do I get the Esc, Ctrl, and arrow keys?

iOS's software keyboard can't produce Esc, Ctrl, Tab, or arrow keys at all — so dotMux adds its own helper keyboard: an accessory bar that sits just above the software keyboard with the keys terminals actually need. It includes:

• Esc, Ctrl, Tab and the other modifier/control keys.
• An arrow joystick — a small drag-pad you nudge toward a direction; press and hold to auto-repeat (great for scrolling shell history or moving in vim).
• Sticky modifiers — tap Ctrl, then a letter, to send the combination.
• Hide to a floating dock when you want more screen for the terminal.

If you pair a hardware keyboard (especially on iPad), those keys come through directly too. Swiping on the terminal scrolls the scrollback; it doesn't move the cursor.

Is it secure? Where are my keys stored?

Your credentials never leave your device. Specifically:

• Secure Enclave keys are generated inside the Secure Enclave, can't be exported, and only ever sign there.
• Imported ed25519 keys and passwords live in the iOS Keychain, protected behind Face ID.
• Everything is device-bound (it uses the Keychain's "this device only, passcode required" protection) and is never synced to iCloud or anywhere else. If you remove your device passcode, the stored credentials are erased.

There are two layers of Face ID: an app-lock when you open dotMux, and a per-credential check each time a key or password is used. A short, configurable grace period (about two minutes by default) avoids re-prompting on quick reconnects. Set it to 0 to be prompted on every single use. An app-switcher privacy cover also hides your terminal in the iOS app switcher.

What's free, and what's paid?

dotMux is free to use, fully featured, for one saved host — tmux control mode, SSH keys, Secure Enclave, Face ID lock, iPad multi-window, all of it.

To save a second host (and beyond), there's a single one-time purchase of US $3.99 ("dotMux — Unlimited Hosts"). It's a non-consumable purchase — not a subscription, no recurring charge. Once you buy it, every additional host is unlimited.

How do I restore my purchase?

If you reinstall dotMux, get a new device, or just want to re-sync your entitlement, tap Restore Purchases — it's on the unlock screen and in Settings. The unlock is tied to your Apple ID, so it restores on any device signed in to the same Apple ID, and survives reinstalls. You won't be charged again.

Does it support mosh, jump hosts, or SFTP?

Not yet — and we'd rather be straight with you than over-promise. The first release is focused on doing SSH plus native tmux control mode really well. The following are deferred for now:

• mosh — deferred. (mosh syncs rendered screen state rather than the raw byte stream that control mode needs, so it isn't a simple add-on.)
• Jump hosts / bastion / ProxyJump — deferred.
• SFTP / file browsing / Files provider — deferred.
• Port forwarding and agent forwarding — deferred.
• iCloud key sync, Mac, and visionOS — deferred.

If one of these is a dealbreaker for you, email dotmux@dotpt.com and tell us — it helps us prioritize.

How do I report a connection bug?

The most useful thing you can send is a Diagnostics export:

1. Go to Settings → Diagnostics and turn it on (it's opt-in and off by default).
2. Reproduce the connection problem.
3. Back in Settings → Diagnostics, tap to export and share the log with us via the iOS share sheet (or email it to dotmux@dotpt.com).

The diagnostics log is an on-device record of the connection/attach process — the commands dotMux ran, session names, state transitions, and a sample of what the host printed before tmux attached. It never records your keystrokes or your terminal output, so it's safe to share.