Docs

Overview

Muxly is an SSH client and terminal emulator for iPhone and iPad, built around tmux. Every host connects in one of two modes:

• Plain SSH — each tab is an independent shell on the connection. Simple, no server requirements.
• tmux integration — Muxly attaches to a tmux server in control mode. Tabs mirror real tmux windows, sessions keep running when you disconnect, and features like session switching and bell notifications become available.

Getting started

1. Add a host. In the Hosts tab, tap + and enter a label, hostname, port (default 22), and username.
2. Choose authentication. Password (stored in the iOS Keychain), SSH key, or none. In the Keys tab you can generate an Ed25519 key (optionally protected by a passphrase) or a Secure Enclave key — hardware-bound, protected by Face ID, and impossible to export from the device. You can also import existing OpenSSH Ed25519 keys from a file or by pasting. Copy the public key to your server's authorized_keys.
3. Connect. On first connection Muxly shows the server's host-key fingerprint and pins it — if the server's key ever changes, you'll be warned before connecting.

The terminal screen

A slim action bar sits at the bottom of every terminal:

• Back — leaves the terminal without disconnecting. The host row shows a green Live badge; tap it to return instantly.
• Tab strip — tap a tab to switch to it. Tabs with unseen output show a blue wedge in the upper-right corner, and the active tab shows ✕ to close it. With tmux integration, a tab whose window has several panes also shows a split icon with the current pane number, for example 1/2 — see Panes.
• + — opens a new tab.
• ⋯ More — opens the File Explorer, Search, and — with tmux integration — Switch Session.

If the blue corner indicator keeps returning after Codex finishes, turn off Codex’s decorative effects.

What a tab is depends on the connection mode:

The blue corner indicator keeps returning after Codex finishes

Codex can keep drawing faint star animations around its input prompt after finishing a response. These animations update the terminal, causing the blue corner indicator to reappear when you switch to another tab. To stop these background updates, turn off Codex’s decorative effects.

Edit ~/.codex/config.toml on the computer where Codex runs:

[tui]
whimsy = false

If [tui] already exists, add or update whimsy in that section. Save the file, then restart Codex and resume your conversation.

For alerts when Codex finishes responding or asks for approval, follow the Codex CLI notifications setup.

Codex configuration schema

Keyboard toolbar and dictation

Above the keyboard, a customizable toolbar provides Esc, Tab, Ctrl, arrows, and more. In Settings → Keyboard Toolbar you can add, remove, and reorder buttons: key chords with modifiers, sticky Ctrl/Alt/Shift, F1–F12, custom text snippets, a multi-arrow overlay, dictation, and Attach Photos.

Dictation is available on iOS and iPadOS 26 or later. Tap the microphone button and speak. Your words appear in a bubble above the keyboard, where you can correct them before they go anywhere. Tap the stop button to send the text to the terminal; if the bubble is empty, nothing is sent. Recognition runs on the device. Dictation also works inside the text editor.

Attach Photos lets you share photos and screenshots with programs running on your host. Tap the photo button in the keyboard toolbar and choose your images. Muxly uploads them to ~/.muxly/photos/ on the host, copies their paths to the clipboard, and inserts them into the original terminal when it is still available. If the button is missing, add it in Settings → Keyboard Toolbar.

Hardware keyboard, mouse, and trackpad

With a hardware keyboard, ⌘ T opens a new tab and ⌘ W closes the current one; Esc dismisses the pane picker. A trackpad or mouse scrolls the terminal and the tab strip, and terminal programs that use the mouse receive clicks.

Selection, search, and links

Select text with drag handles and a magnifier, then copy or paste with the system clipboard. Search, under ⋯ More, finds text in the terminal with previous and next match. Tapping an http or https link asks for confirmation, then opens it in your browser.

tmux integration

For the complete connection and reattachment workflow, follow Use tmux on iPhone and iPad.

With tmux Integration enabled for a host, Muxly attaches to the tmux server in control mode. The terminal becomes a native window into tmux: scrollback and touch gestures work natively, and the text status line is replaced by the tab strip. Requires tmux 3.2 or newer on the server; turn it on per host under Edit Host → tmux Integration.

Muxly verifies both the installed tmux executable and any already-running tmux server. Both must report tmux 3.2 or newer.

Sessions

Each host has a Session Behavior setting that decides what happens when you connect:

• Resume Last Session (default) — reconnects to the session you last used on this host. If it's gone, or you haven't used one yet, Muxly asks you to create or choose a session instead.
• Choose Existing Session — shows the list of sessions on the server on every new connection.
• Create or Choose — offers a menu on every new connection: new session, new named session, or attach to an existing one.

Session names can't contain : or .. If a name already exists you can attach to it instead. New sessions are created at your device's exact terminal size.

Switching while connected: tap ⋯ More → Switch Session. The list shows every session with its window count and marks sessions attached from elsewhere. Switching happens instantly over the live connection — no reconnect.

Creating while connected: in Muxly 1.1.3 or later, open ⋯ More → Switch Session, tap + in the switcher, and choose New Session or New Named Session…. For a named session, enter a name and tap Create. Muxly opens the new session over your existing connection. If the name already exists, you can switch to that session or choose another name.

Sessions keep running. tmux sessions live on the server, not on your phone:

• Going Back to the host list keeps the connection alive (Live badge).
• Backgrounding the app never kills your session. If iOS drops the connection while the app is suspended, Muxly reconnects and re-attaches when you return.
• prefix d performs a real detach — the session keeps running headless, and you can re-attach any time.
• If the session is killed from elsewhere, Muxly shows [tmux session ended] and offers to reconnect; the next connection asks you to create or choose a session.

The per-host Keep Alive heartbeat (default every 30 s) prevents idle disconnects.

Windows & tabs

With tmux integration, every tab is a tmux window — on iPhone and iPad alike. Tapping + creates a new window and opens it in Muxly without changing what other attached clients see. By default it goes after the last window; see Use tmux default tab placement.

• Rename: long-press a tab → Rename Tab. This renames the tmux window, so every attached client sees the new name. Submit an empty name to restore tmux's automatic naming.
• Reorder: long-press a tab → Move Tab Left / Move Tab Right. This swaps the window with its neighbour for every client.
• Labels: an explicit tmux window name wins. Otherwise Muxly uses the pane's terminal title where available, then the current command or tmux's automatic name, and finally Window N.
• Close: ✕ closes the whole window, including all its panes. Use Tab close protection in Settings → Terminal Behavior to choose when Muxly asks for confirmation.

Windows created, renamed, or closed by other clients appear in the tab strip live.

Panes

A tmux window can be split into panes. How Muxly shows them depends on how much room it has:

• iPad at full width: panes appear together inside the tab, in the same layout as on the server. Floating panes appear over the other panes, matching their position on the server. Tap a pane to focus it. When several panes are visible, tap ✕ in the focused pane’s upper-right corner to close that pane.
• iPhone, and iPad in a narrow window: you see one pane at a time. The tab shows a split icon with the current pane and the total. A blue wedge in its upper-right corner means a hidden pane has new output. Tap the active tab to open the pane picker. It shows a miniature layout, or a grid of pane buttons when there are floating panes or the layout is too small to tap comfortably. Unread panes show the same blue corner indicator in the picker. Tap a pane to switch to it. Tap ✕ on the selected pane in the picker to close it. Tap outside the picker (or press Esc) to dismiss it.

A modal pane temporarily prevents interaction with the other panes in its window.

The layout mode is chosen when you connect. Create panes with prefix % and prefix ", and move focus with prefix + arrow keys.

Prefix shortcuts

Muxly reads the prefix key of the session you're attached to (default Ctrl+B), including a secondary prefix if you've configured one, and handles these shortcuts natively:

c new window · & close window · x close pane · % and " split · n / p next / previous window · 0–9 select window · arrows focus pane · d detach · prefix twice sends it literally · Esc cancels a pending prefix.

& and x ask for confirmation first — answer with y or n, as in tmux. Other prefix shortcuts aren't handled by Muxly and show a tmux shortcut not supported notice.

Startup command & environment

In tmux mode, a host's Startup Command and environment variables apply only to fresh, Muxly-created sessions and to windows opened with + — never when re-attaching to an existing session.

Files & editing

File Explorer

Open it from ⋯ More → File Explorer. It's an SFTP browser for the connected host. Each tab has its own File Explorer, and it stays open — together with any file you're editing — while you switch between terminal tabs. Return to Terminal takes you back.

• Browse: tap folders to navigate, use the path bar to jump back up, and type in Filter files to narrow long listings. Get Info shows a file's name, path, type, size, modified date, and permissions; Copy Path copies its full path.
• Refresh: pull down on the file list to reload the current folder.
• Manage: New File, New Folder, Rename, and Delete.
• Upload: Upload Files picks from the Files app; Upload Photos picks from your photo library.
• Download: Download… saves a file to the Files app. For images and videos, Save to Photos adds them to your photo library.

When a name already exists, Muxly asks whether to Overwrite, Keep Both, or Skip.

If SSH reconnects while your tabs remain open, Muxly automatically restores file access and refreshes their open folders. Your current folder, filter, sort order, and hidden-file preference are preserved.

Text editor

Tap a text file to open it in the built-in editor, with syntax highlighting for common languages (Swift, Python, JavaScript, TypeScript, Go, Rust, C, C++, Java, Ruby, PHP, HTML, CSS, JSON, YAML, TOML, Markdown, shell scripts, SQL, Lua, and R). Files up to 5 MB can be edited; binary and special files can't be opened.

Tap Save to write the file back. Saving keeps the file's owner and permissions. If the file changed on the server while you were editing, Muxly warns you before overwriting it.

Unsaved edits survive switching tabs and connection recovery while the tab remains open. Reconnecting does not reload the open file or replace your changes. Saving becomes available again when file access is restored. If you leave a file with unsaved changes, Muxly keeps a copy and offers to restore it the next time you open that file.

Dictation works in the editor on iOS and iPadOS 26 or later.

Bell notifications

Follow the terminal-notifications walkthrough for a test bell and task examples.

Muxly can send a push notification when a program in your tmux session rings the terminal bell (BEL) — a long build finishing, an agent needing input, an alert firing.

How it works

When a bell rings, a hook that Muxly installs in the tmux server (held in tmux's memory only — nothing is written to your server's disk) encrypts the session and window details and posts them straight from your server to the Muxly relay. The relay forwards the sealed envelope through Apple's push service, and your device decrypts it locally. The relay never has the encryption key — it sees routing data and a generic "Terminal Bell" alert, never your session or window names. And because the server posts the bell itself, notifications arrive even when Muxly is closed and the SSH connection is long gone.

Setup

1. Turn on Bell Notifications in Settings, and allow notifications when iOS asks.
2. In the host's settings, enable tmux Integration and Notify for This Host.
3. Connect to the host once. Muxly verifies the server (tmux 3.2 or newer, openssl, curl), installs the hook, and registers with the relay — the status line under the toggle reports progress and ends at Ready.
4. Test it: run sleep 10; printf '\a' in the session, then background the app.

What you get

The notification is titled with the host's name, with the session and window as the body. Repeated bells from the same window replace each other instead of stacking, and no banner is shown while you're already looking at the window that rang. Tapping a notification jumps straight to that session and window if a connection is live; otherwise it highlights the host to connect to.

AI coding agents

Configure your agent to emit a terminal bell for supported attention events. The notifications guide maintains the current Codex CLI configuration and Claude Code configuration and timing.

First complete the basic bell test to verify delivery independently of the agent.

Requirements & limits

• Bell notifications require tmux integration — they're not available for plain SSH connections.
• Only sessions Muxly has attached to (while notifications were enabled) can ring.
• Your tmux config must allow bells (monitor-bell on, bell-action not none). Muxly detects misconfiguration and suggests the exact fix commands, but never changes your tmux options itself.
• The server needs outbound HTTPS and a clock within about 30 seconds of your device.
• To receive bells on multiple devices, enable iCloud Keychain so they share the delivery identity.
• Delivery is best-effort — notifications can be delayed or dropped, so don't rely on them for anything critical.

Settings reference

Appearance

App Appearance — choose Automatic, Light, or Dark, independently of your terminal theme. Automatic is the default and follows your device’s appearance. Changes apply immediately.

Terminal Appearance

Four themes (Midnight, Charcoal, Paper, Ocean), twelve monospace fonts, and five text sizes, with a live preview. Changes take effect when you reconnect.

Keyboard Toolbar

Customize the buttons shown above the terminal keyboard — add, remove, and reorder key chords, F1–F12, snippets, sticky modifiers, the multi-arrow overlay, dictation, and Attach Photos. Changes apply immediately.

Terminal Behavior

Scrollback Lines — how many lines of history each terminal keeps (100 to 1,000,000; default 10,000).

Trim trailing blank rows — controls what happens to the empty space below your last line of output.

• Off (default): the terminal grid resizes to fit above the keyboard, and you can scroll across the whole grid — including blank rows beneath the prompt, so after clear the prompt sits at the top with empty space below it.
• On: the terminal keeps its full height and the content ends just below the last printed row, so output stays flush against the keyboard — and showing or hiding the keyboard no longer resizes the remote terminal.

Turn it on if you want bottom-anchored output; leave it off if full-screen apps or clear behave oddly.

Tab close protection — choose when Muxly asks before closing an SSH or tmux tab:

• Off (default): close without confirmation.
• Recently active: ask before closing a tab that received output in the last two seconds. Newly created tabs have a brief grace period.
• All: ask before closing any connected tab, including idle and newly created tabs.

Applies to the tab’s ✕ button and ⌘ W. Unsaved files still require confirmation in every mode. Changes apply immediately.

Under Advanced:

Use tmux default tab placement — where a new tab's tmux window is created.

• Off (default): new tabs always append after the last window, so tab order matches the order you created them in.
• On: tmux picks the lowest unused window index — the same as running new-window yourself: it fills gaps left by killed windows and honors your base-index.

App Lock

Lock Muxly behind Face ID or Touch ID (device passcode as fallback), re-locking immediately or after 1, 5, or 15 minutes.

Bell Notifications

The global switch for bell notifications. If a delivery-identity conflict is ever detected (for example after restoring a backup to a different device), a Reset Bell Delivery Identity action appears here — resetting rotates the delivery channel and encryption key, and you reconnect to each server once to replace its hook.

Purchases

Shows your unlock status, and lets you unlock Muxly, manage a subscription, or restore purchases.

Help & Feedback

Send Feedback for ideas and questions, Report a Bug for problems, and Licenses for open-source software and font licenses. To start a bug report by shaking your device, enable Settings → Help & Feedback → Shake to Report a Bug, which is off by default. The Muxly version is shown at the bottom of Settings.

Per-host settings

• Connection — label, hostname, port, username.
• Authentication — password, SSH key, or none.
• Startup Command — runs after connecting in each new shell; in tmux mode, only in fresh Muxly-created sessions and + windows.
• Environment Variables — sent as SSH environment requests; note that servers only accept names allowed by their AcceptEnv configuration.
• Port Forwarding — local, remote, and dynamic (SOCKS proxy) tunnels; active while Muxly is open.
• tmux — tmux Integration, Session Behavior, and Notify for This Host.
• Advanced — Keep Alive, the heartbeat interval that prevents idle disconnects (default 30 s; 0 disables).

Privacy & security

Muxly has no accounts, no ads, and no analytics SDKs. Host configurations stay in the app's local database; passwords and private keys live in the iOS Keychain, and Secure Enclave keys never leave the chip. Hosts and keys are deliberately not synced between devices. Terminal traffic goes to your servers only, and bell content is end-to-end encrypted past the relay. Dictation is recognized on the device, and photo library and Files access is used only for transfers you start. Details in the Privacy Policy.

FAQ

Do my sessions die when I close the app?

Not with tmux integration — sessions run on the server, and Muxly re-attaches when you come back. Plain SSH tabs end when the connection ends.

How do I switch between panes on iPhone?

Tap the active tab to open the pane picker, then tap the pane you want. See Panes.

Why can't I rename or reorder a tab?

Renaming and reordering require tmux integration. Long-press a tmux tab to open its menu.

Why does a tmux shortcut show "not supported"?

Muxly handles the shortcuts listed under Prefix shortcuts itself and doesn't pass others through to tmux.

Where is the dictation button?

Dictation requires iOS or iPadOS 26 or later. If you removed the button, add it back in Settings → Keyboard Toolbar.

Can I use a hardware keyboard?

Yes. ⌘ T opens a tab and ⌘ W closes one, and the keyboard toolbar remains available for keys your keyboard lacks.

Bells aren't arriving — what should I check?

Both toggles (global Bell Notifications and the host's Notify for This Host) are on; you've connected to the host at least once since enabling them and the host's bell status reads Ready; iOS notification permission is granted; your tmux config allows bells (monitor-bell on, bell-action any); and the program actually emits BEL. For AI coding agents, check the agent's notification setting.

Do my hosts and keys sync over iCloud?

No — they stay on the device, by design. To use a key on another device, export it (Secure Enclave keys can't be exported) or generate a separate key per device.