Terminal

Opening a terminal

Open a terminal from a host's tile or page, a link, or a Shortcut. On a Mac or an iPad keyboard, the Connect menu has Terminal, ⌥⌘2, for the host in front. On a Mac, Conn's menu bar icon lists your hosts and sessions too.

Conn signs in with the host's saved password or key (asking for Face ID or Touch ID if it's protected), or asks you for one. It tells the host it's an xterm-256color terminal, and sends your language setting when the host has it, C.UTF-8 when the host has only that, and nothing otherwise. Each terminal keeps 10,000 lines you can scroll back through.

The first time you connect to a machine, Conn remembers its SSH key. If the key ever changes, Conn stops and asks before going on. See Server keys.

tmux or a single session

The first time you open a terminal on a host, Conn asks How should this terminal run?:

tmux

Keeps running on the host after you leave. What you start carries on when Conn closes or the link drops, and Conn puts you back in it. This answer is kept with the host in Conn, so with iCloud sync on it holds on all your devices.

Single session

Ends when you close it or the link drops. This answer holds on this device only.

Turn on Use this for new hosts too and Conn stops asking: your answer becomes the New Terminals setting (Settings, Terminal: Ask, Single session or tmux). To change one host, use Runs In in Edit Host, Terminal.

How Conn uses tmux

• Conn runs its own tmux server on the host, separate from yours, so its settings never change your own tmux. Your own sessions still show in Sessions, as Other tmux.
• The first terminal on a host uses a session called conn. A second terminal on the same host gets its own, shell-2, so the two don't share a screen.
• On its server, Conn turns on the mouse, the clipboard, focus events and a short Escape delay, and keeps about 10,000 lines of history.
• Conn needs tmux 2.1 or later.

Installing tmux

If a host has no tmux, the terminal says so and opens as a single session, with Install tmux. Conn shows you the command first, then types it in the terminal when you press Install. You type your own password when the host asks; Conn never sees it.

• Conn knows apt, dnf, yum, zypper, pacman, apk, pkg, Homebrew and MacPorts, adds sudo or doas where needed, and never answers yes for you.
• When it's done, Switch to tmux opens tmux in the same terminal. If the banner still says Installing, Check Again asks the host.
• On a Mac with Apple silicon and macOS 15 or later, and no Homebrew or MacPorts, Install tmux for This Account puts a copy of tmux in ~/.conn/bin, checked before it's installed. Remove Conn's tmux in Settings, Terminal takes it away again.
• Conn types only at a shell prompt. If a program has the screen, quit it first.

When the link drops

A banner says why the session ended, such as the shell exiting or the connection going. Reconnect, in the banner or the toolbar, connects again:

• With tmux, you're put back in your tmux session: Reattached to your tmux session, everything as you left it. If that can't happen, the banner says why, and Attach tries again where your session may still be there.
• As a single session, you get a new shell on the host.
• Nothing you typed while the link was down is sent again.

Coming back by itself

A tmux terminal comes back on its own: on iPhone and iPad when you return to Conn after its link went, and on a Mac when it wakes or a link goes while you use it.

• It signs in with the password or key saved for the host. One opened with Use Once waits for you to press Reconnect.
• It never asks for a sign in, and won't connect to a machine whose key is unknown or changed.
• A host's terminals come back one after another, with a single Face ID or Touch ID check.
• A single session never comes back by itself; it keeps its Reconnect button.

iPhoneiPad iOS pauses Conn soon after you leave it, and the SSH link can't stay open in the background. When you come back, Conn first checks each connection with the host (Checking the connection to the host), and the keyboard returns when it answers. With tmux, your work carried on the whole time.

Typing

The key bar

iPhoneiPad Tap the terminal for the keyboard. The key bar above it has the keys a phone keyboard lacks, on three pages:

Page	Keys
Usual	esc tab ctrl alt, the arrows, ~ | / -, then ai and fn
fn	PgUp PgDn Home End, F1 to F12, ⌘ (Run a Command), abc to go back
ai	esc, ⇧⇥, a sticky ⇧, the arrows, Return, a new line key, ctrl, / @, abc

• The key at the right end puts the keyboard away.
• Tap ctrl or alt and it applies to the next key. Tap it twice to keep it on, and once more to turn it off. ctrl then c stops a running program.
• The arrows, PgUp and PgDn repeat while you hold them.
• At larger text sizes the bar wraps onto more rows rather than squashing its keys.
• With a hardware keyboard, the bar sits at the foot of the screen, and ⌘. is Escape.

On a Mac

The menu bar keeps its own shortcuts, such as ⌘Q and ⌘W. Every other key goes to the host. Conn's shortcuts all use ⌘, so none takes a Control chord from the terminal.

The Option key

• Use Option as Meta (Settings, Terminal; off by default): off, Option types characters as it does everywhere else; on, Option and a key send Escape then that key, which Emacs and the shell read as Meta. On a British layout, Option+3 stops typing # while it's on.
• Option Arrows: Word (the default) moves by word in bash and zsh; xterm sends codes a program such as tmux can tell apart.

AI coding tools

Conn has no AI of its own, but works well with tools you run on your machine, such as Claude Code, Codex and Gemini. Start one with New Session, and Sessions shows when it's waiting for you.

• iPhoneiPad The ai page has keys for them. A tool started from New Session opens on it. ⇧⇥ changes Claude Code's mode, and the new line key adds a line without sending.
• With a keyboard, ⌃J and ⌥Return add a line without sending, and so does ⇧Return in a tool started from New Session. Their other Option shortcuts need Use Option as Meta.
• Conn tells these tools when you leave and come back, so they can react.
• Signing in to Claude Code: /login prints an address. Tap it (⌘-click on a Mac), sign in, copy the code and paste it back. On iPhone and iPad, do this in a tmux session, so the trip to the browser can't lose it. On a Mac host over SSH, Claude says Not logged in until the keychain is unlocked: use Unlock Keychain in the ⋯ menu, run /login once, or run claude setup-token. Unlock Keychain is offered in a running tmux session Conn opened.

Scrolling, selecting and copying

Scrolling

• iPhoneiPad Drag up or down to scroll back, or scroll with a trackpad or mouse.
• In a program that uses the mouse, such as Claude Code, the program scrolls instead. Mac Hold Shift as you scroll to scroll Conn's own history.
• In tmux, scrolling over a shell goes into tmux's history. Press q, or scroll to the bottom, to leave it.
• Mac Clear Scrollback, ⌘K, clears the history and the screen except the line you're typing. A full-screen program, tmux included, keeps its own.

Selecting and copying

• iPhoneiPad Touch and hold the text, then drag to select it, and lift your finger for Copy. Touch and hold anywhere for Paste, or Select All to copy the whole screen.
• Mac Drag across text, then ⌘C and ⌘V. Hold Option as you drag to select a rectangle, such as one column. In a program that uses the mouse, such as vim or htop, hold Shift as you drag. Services in the Conn menu send a selection to another app.
• In tmux on a Mac, a drag selects in tmux, and tmux's copy reaches your device. On iPhone and iPad a trackpad or mouse drag does the same; a finger's drag scrolls.

Pasting

If a paste has a line break in it, and the program isn't ready for a paste, Conn asks first (Paste and run so many lines), because each line break runs the line before it. Control characters are taken out of every paste (tabs are kept).

When a program copies to your device

A program on the host can ask to put text on your clipboard, as Claude Code's /copy does. Conn asks wants to copy to this device. Allow? until you allow that host. The hosts you've allowed are under Can copy to this device in Settings, Terminal, with Remove.

Links

Web links (http and https) are underlined. On iPhone and iPad, tap one to open it, or touch and hold for Open Link and Copy Link. On a Mac, ⌘-click to open it, or right click for the menu. A link whose text isn't its address asks before opening.

Smart View

The table button reads the last command's output and, when it can, shows it as a table or a chart, for commands such as df and free. In tmux it reads only what's on the screen, so output taller than the screen stays in the terminal. In a narrow window, such as an iPhone's, Smart View is in the ⋯ menu. Keyboard: ⇧⌘M.

The ⋯ menu

• New Session... starts something else on this host. See Sessions.
• Unlock Keychain, for a Mac host: you type the Mac's password to unlock its keychain for tools that need it.
• End Session, for a tmux terminal, stops the session on the host and whatever it runs. Closing it in Sessions instead leaves it running.
• Help, last, explains everything on screen, with Show the Tour at the end.

When the bar has no room, other buttons fold into this menu too.

More than one session

• With two or more sessions open, the stack button with the count lists them, to switch between.
• iPad Show Beside, in a wide window, puts a second session next to this one. Open in New Window gives a session a window of its own. On an iPhone, Show Beside works in landscape on larger models.
• Mac Each session can have its own window (Open in New Window). On macOS 15 or later, right click the toolbar to choose its buttons. In full screen, a new terminal window may open as a tab, as macOS's settings choose.
• Handoff picks up a tmux session on your other devices. That device signs in with its own saved sign in, and both need iCloud sync on. A single session, or one marked Other tmux, can't be handed over. See Handoff.

iPhone Duo

With the display folded halfway like a laptop and the keyboard up, the terminal stays on the top half and the keyboard is on the bottom. A vertical book fold leaves the layout as it is.

Appearance

• Theme: Conn Dark (the default), Conn Light, Solarized Dark, Solarized Light, Dracula, Nord, One Dark, Gruvbox Dark, Gruvbox Light and Plain. Programs that ask for the terminal's colours, such as Claude Code, Codex and tmux, are told the theme's, so they match. If a theme has colours that are hard to read, Settings says which.
• Font: System monospaced (the default), Menlo, JetBrains Mono, Fira Code or IBM Plex Mono, in Regular, Medium or Semibold.
• Size: 8 to 32 points, 13 by default. ⌘+, ⌘- and ⌘0 change it in every terminal at once.
• Ligatures (off by default) join sequences such as != and -> into one symbol, in fonts that have them, such as Fira Code and JetBrains Mono.
• The cursor's shape and blinking follow what the program asks for, except that with Reduce Motion on the cursor doesn't blink.
• These settings belong to each device; they don't sync.

Terminal settings

Setting	Where	Default
New Terminals	Settings, Terminal	Ask
Theme, Font, Size, Weight, Ligatures	Settings, Terminal	Conn Dark, System monospaced, 13, Regular, off
Use Option as Meta	Settings, Terminal	Off
Option Arrows	Settings, Terminal	Word
Can copy to this device	Settings, Terminal	No hosts
Notify When a Session Needs You	Settings, Terminal (Mac)	On
Runs In	Edit Host, Terminal	Follows New Terminals
Remember Commands Run Here	Edit Host, Terminal	On

Keyboard shortcuts

Keys	Does	Where
⌥⌘2	Terminal, for the host in front	Mac, iPad
⌘T	New Session...	Mac, iPad
⇧⌘P	Run a Command (the palette)	Mac, iPad
⇧⌘M	Smart View	Mac, iPad
⌘R	Reconnect	Mac, iPad
⌘+ ⌘- ⌘0	Bigger, Smaller, Default Size	Mac, iPad
⌘K	Clear Scrollback	Mac
⌘.	Escape	iPhone, iPad with a keyboard

All of Conn's shortcuts are in Keyboard shortcuts, and the messages a terminal can show are in Troubleshooting.