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 — for step-by-step how-tos across every feature, see the guide.

Contact

Stuck on something not covered here, or found a bug? Email info@dotmux.app. 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, where a layout-proportional pane minimap in the tab bar expands into a pane picker you tap 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.

How do I split, resize, or close panes?

Open the pane menu — the pane button in the tab bar, a long-press on an unfocused pane, or a right-click with a trackpad — and pick Split Right, Split Down, Resize, Equalize, or Close Pane…. On iPad you can also drag the divider, and a hardware keyboard uses ⌘D / ⇧⌘D to split, ⇧⌘W to close, and ⌃⌘-arrows to resize. Every operation runs through tmux itself, so if tmux refuses — a pane too small to split, say — you see its own error rather than a fake success. Full details in the guide →

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.)

Why is my terminal letterboxed, with a badge naming another device?

tmux sizes a shared window to its smallest attached client, so when another device (a laptop, say) is attached to the same session at a different size, dotMux adopts that size and letterboxes to match — the badge just names who imposed it. Type anything, or tap the badge, to reclaim your full size. It isn't a bug; it's tmux keeping every client's view of the window consistent. Full details in the guide →

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.

The bar is fully customizable, too: in Settings → Keyboard → Customize Keyboard Bar you can add, remove, and reorder keys, add your own text snippets, and export or import the whole layout as a JSON file. Full details in the guide →

Can I change the theme, font, or keyboard bar?

Yes — dotMux is meant to be made your own. In Settings → Terminal you'll find ten live-preview color themes (Dracula, Nord, Solarized, Gruvbox, Tokyo Night, Catppuccin and more), six monospaced fonts, an adjustable font size, and pinch-to-zoom. The helper keyboard bar is fully editable as well — add, remove, and reorder keys, add custom text snippets, and carry the layout between devices as a JSON file. See themes & fonts and the keyboard in the guide.

Can I paste images into Claude Code (or other CLIs)?

Yes. Copy an image on your iPhone or iPad, then paste it in a remote session — dotMux uploads the image to the host and drops its path into the focused pane. In Claude Code that path attaches inline as [Image #1]; with other tools you get the path right there in your prompt to reference however that tool expects.

Here's why it needs a bridge: a CLI reads images from the clipboard of the machine it runs on. A headless SSH host has no clipboard (and no display), so its own Ctrl-V has nothing to grab. Instead, dotMux uploads the image bytes over a second SFTP channel on the same SSH connection, into a folder in your own home directory (~/.dotmux/paste/), then sends only the resulting file path into the focused pane as a bracketed paste — which is what lets Claude Code attach it as an image rather than treat it as text. The image bytes never travel through the tmux stream, and no Enter is sent, so you add your prompt and submit when you're ready.

• Formats & size — images are converted to a supported format (PNG, JPEG, or GIF) and kept under Claude's limits. HEIC photos become PNG/JPEG automatically. An image that can't be brought under the size cap is dropped (you'll feel a failure haptic) rather than sent, because an oversize image can wedge the session.
• Privacy — location and other photo metadata (EXIF/GPS) is stripped on the device before the image is uploaded, so a geotagged photo doesn't leak where you were. As always, the transfer is straight to your server — nothing passes through any dotMux backend.
• Cleanup — uploaded files are written privately (owner-only) and clean themselves up: only the most recent few per window are kept, anything older than a day is pruned, and a window's files are removed when you close it.
• Text paste is unchanged — pasting text works exactly as before; an image just takes precedence when the clipboard has one.

The upload and path injection happen regardless of what's running in the pane. Claude Code is the seamless case — it turns a pasted bare path into an inline image on its own. Other CLIs attach files their own way (a launch flag, an /add command, an @path mention), so you may need to wrap the pasted path in their syntax; a built-in per-tool option is a possible future addition. Full details in the guide →

How do I select and copy text — especially out of Claude Code?

In a normal pane (a shell prompt, a log), long-press the text: dotMux shows a selection with drag handles and a Copy menu, like any iOS text view.

Full-screen apps like Claude Code are different: they capture the mouse and re-wrap their text to fit the screen, so copying the screen as-is would bake those visual line breaks into your clipboard. Over these apps, dotMux hands your gesture to the app itself:

• Long-press, then drag in one motion — Claude Code renders its own highlight as you sweep. Lift your finger, and the app's copy lands on your device clipboard (you'll feel a success haptic). A transcript line that was wrapped on screen arrives as one logical line — no stray line breaks, no indent artifacts.
• Long-press without dragging — after a moment dotMux falls back to its own selection with handles and a Copy menu. Handy for grabbing exactly what's on screen, but the text is copied as displayed, wrap points included.
• Apps that capture the mouse but never copy (htop, vim with mouse mode) fall back to the handle selection the same way.

The app-copy path needs tmux 3.4 or newer on the host for the instant handoff; dotMux configures the rest automatically. There's also an opt-in extra in Settings — Mirror tmux Buffer Copies — that puts text you copy in any attached tmux client (say, copy-mode on your laptop) onto this device's clipboard too. Full details in the guide →

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 grace period (about two minutes) avoids re-prompting on quick reconnects. 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 $1.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. (dotMux already uses SFTP under the hood to paste images into remote sessions; a user-facing file browser just isn't here yet.)
• Port forwarding and agent forwarding — deferred.
• iCloud key sync, Mac, and visionOS — deferred.

If one of these is a dealbreaker for you, email info@dotmux.app 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 info@dotmux.app).

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.