Help

1. Requirements
2. First connection
3. Tailscale and private networks
4. tmux
5. Keyboard and input
6. Agents and notifications
7. Trial and purchase
8. Troubleshooting
9. Contact

Requirements

• iOS 16 or later, on iPhone or iPad.
• A server you can reach over SSH with a password or a key. Sigmux speaks SSH directly to it; nothing needs to be installed on the server for the terminal itself.
• tmux 3.2 or newer on the server for control mode, the mode that turns windows and panes into native controls. tmux 3.3+ lets each window keep its own size. Older tmux works through classic attach, and a plain shell works on any host.
• For agent notifications: Claude Code, Codex or OpenCode installed on the server, and either the Sigmux relay or a push service of your own (Bark, ntfy or a webhook). See Agents and notifications.

First connection

1. Tap + on the Hosts screen. Enter a name, the host name or address, the port and the username.
2. Choose how to sign in. Password is stored in the iOS Keychain. For a key, Generate new key makes an ed25519 key on the phone (you copy its public half to the server's authorized_keys), or Import new brings in a key you already have. Keys never leave the device.
3. Under Connect to, pick tmux or a plain shell. For tmux, pick Control mode (tmux 3.2+) or Classic attach, and a session name; Sigmux attaches to it and creates it if it does not exist. The first time, with more than one session on the host, you choose one.
4. Tap the host. On the first connection Sigmux shows the server's host key fingerprint and asks you to accept it; it is remembered and checked on every later connection.

Sigmux locks itself with Face ID or Touch ID (App Lock in Settings). Everything you save, hosts, credentials and settings, stays on the phone.

Tailscale and private networks

Many Sigmux users reach their servers over Tailscale (or another WireGuard mesh). Sigmux does not care: it is an SSH client, and a tailnet address is just an address. What does matter is whether the phone's path to the server is direct or goes through a relay, because a relayed path from a phone on cellular commonly has a round trip of 300 to 700 ms. Everything still works, but connecting takes seconds, every keystroke echoes late, and the tmux handshake can hit its timeout.

Set the host up once

• Use the MagicDNS name (mac.tailnet-name.ts.net or just mac) or the stable 100.x.y.z address as the host name. Both survive IP changes, so the remembered host key keeps matching.
• Keep the ordinary SSH server (OpenSSH) listening and sign in with a key, as on any host. Tailscale SSH with "check mode" asks you to confirm in a browser before each login; Sigmux has no browser to do that in, so either exempt the phone from check mode in your ACL or keep OpenSSH.
• Leave the server awake. A Mac that sleeps does not answer; in System Settings turn off sleep while on power, or run caffeinate -s in a tmux window you keep around.

Get a direct path

A phone on cellular sits behind carrier NAT, so the connection can only be direct if the server's side can be reached. Check with tailscale status on the server: a line that says relay "hkg" (or any relay name) next to the phone means every byte goes through that relay; direct with an address means you are done. Then, in order of effect:

1. IPv6 at home or on the VPS. Carriers hand phones IPv6; if the server has a public IPv6 address too, Tailscale connects directly without any NAT tricks. This is the single most effective change.
2. Let the router map a port. Enable UPnP or NAT-PMP on the home router, or forward one UDP port to the server and pin Tailscale to it: tailscale up --port=41641 (keep your other flags) and forward UDP 41641. On a cloud VM, open UDP 41641 inbound in the security group.
3. Avoid double NAT. A 5G home gateway or an ISP modem in front of your own router usually means two NATs and no hole punching. Put the modem in bridge mode, or use the ISP's IPv6.
4. A relay of your own nearby. If the server must stay behind a hard NAT, a small VPS in the same region as the phone running a custom DERP (or acting as a Tailscale peer relay) cuts the round trip to tens of milliseconds, still relayed but close.

tailscale netcheck on the server reports the NAT type and whether a port mapping was found; "MappingVariesByDestIP: true" with no mapping is the case that only IPv6 or a forwarded port fixes.

Living with a relayed link

• Keep sessions attached rather than closing them: reconnecting into the same tmux session is one tap from the Disconnected band and costs one handshake, and nothing is lost on the server meanwhile.
• Use Compose for anything longer than a command; typing character by character over a 500 ms echo is miserable, one paste is not.
• Raise the host's Keepalive interval a little if the cellular link drops the SSH connection often; the default is tuned for direct paths.
• Agent notifications do not use the tailnet at all: the hook on the server posts to the relay (or your Bark, ntfy or webhook) over the public internet, so the server needs outbound HTTPS and the phone needs nothing but its own connectivity.

tmux

Control mode

In control mode Sigmux attaches as a tmux control client. Windows and panes are listed in the palette: tap the window name in the title bar, or the tmux key on the key row. From there you switch, split, rename and close, and create new windows. Output in a window you are not looking at marks that window in the palette; a bell or an agent notification marks it too.

Switching windows does not replay what happened in the window since you last saw it. Sigmux asks tmux for the window's screen and the last 1,000 lines of its history and draws those, so the switch is immediate and the scrollback is what tmux has. Your own tmux prefix keys still work.

Classic attach and plain shells

Classic attach runs the ordinary tmux attach in a terminal, for servers with an older tmux. A plain shell is just a shell. In both, Sigmux can still show the tmux palette and key row: set tmux controls on the host to Auto (shown while a tmux is detected), On or Off, and set the Prefix (Ctrl-b or Ctrl-a) so the palette can drive tmux through keystrokes. If you start tmux with a custom socket, enter the path that tmux display-message -p '#{socket_path}' prints.

Server-side settings worth having

• On tmux 3.7, add this to ~/.tmux.conf and reconnect, so full-screen programs redraw without flicker (tmux 3.8 detects it by itself):

  set -as terminal-features ',xterm-256color:sync'

• If your prompt shows up twice in the scrollback after a resize, add:

  set -g scroll-on-clear off

Busy windows and slow links

When a window produces output faster than the link can carry it, tmux pauses that window for Sigmux instead of letting everything queue behind it. The window you are looking at is resumed at once and redrawn from a fresh capture; a window you are not looking at stays paused until you open it. Hosts whose session is not on screen are paused the same way, so keeping three servers attached costs about what one does.

Keyboard and input

• Showing and hiding the keyboard. Tap the terminal to bring it up; drag down on the terminal to put it away. Scrolling never raises it. Keys on the key row that type something (Tab, the symbols) do raise it; Esc and the arrows do not.
• The key row. Esc, Tab, Ctrl, Alt, Shift, arrows, paging and the symbols a shell needs, with Shift+Tab for the tools that use it. Tap Ctrl, Alt or Shift to arm it for the next key; hold it for half a second to lock it until you tap it again.
• Compose. The pencil key opens a real text field for longer input, with cursor movement and dictation. Send pastes it into the terminal as one paste (bracketed when the program asks for it). Drafts survive leaving the session.
• Files and images. From Compose, attach a screenshot, a photo or a file from Files; it is uploaded to the host and its path pasted. Sharing text, an image or a file to Sigmux from another app lands in an inbox you can send to a host later.
• Hardware keyboards send Ctrl, Esc, arrows and function keys directly; arrows and deletes repeat while held.
• Reading. Tap a URL to open it; tap a file path in agent output to read the file. Long-press to select a word, a path or a quoted string with the system handles and menu. The search key finds text in the scrollback.
• Chinese and other IMEs work in the terminal and in Compose; composition shows above the cursor and is sent when confirmed.

Agents and notifications

A coding agent on your server (Claude Code, Codex or OpenCode) can notify the phone when it finishes or waits for an approval, and you can answer Allow or Deny from the notification. The answer travels over your own SSH connection to your own server; nothing runs anywhere else.

1. In Settings → Agents, turn notifications on and choose a service: Sigmux (the relay we run; it forwards an envelope encrypted on your server and cannot read it), or your own Bark, ntfy or Webhook endpoint.
2. Under On your hosts, install on each host. Sigmux signs in with that host's credential and writes the agent hooks; nothing runs in the background on the host, the agents call the hook when they need you. Remove from host undoes it, with or without a purchase.
3. Send a test notification checks the path end to end. "Break through Focus" marks a waiting approval as time-sensitive; "Include the message" puts the agent's words in the notification.

Inside a session, a waiting approval shows as a card above the key row with the same Allow and Deny, and the conversation can be read as native text instead of terminal scroll. A file the agent mentions opens in a reader; the git changes it made open as a diff.

Trial and purchase

• Sigmux is free to try for 14 days. The trial starts only when you tap Start 14-day trial (a zero-price App Store transaction), not when you install the app or add a host. It never charges and never renews.
• After the trial, a one-time purchase unlocks Sigmux for good, with Family Sharing. No subscription. The price is shown in the app in your local currency.
• When a trial ends without a purchase: opening a new connection and answering an agent approval from a notification need the purchase. A session that is already open keeps working until you close it. Your hosts, keys, settings and drafts stay, and you can still remove hooks from your servers.
• Restore Purchases (Settings → Sigmux) brings back a purchase or the original trial on a new phone; restoring an expired trial does not restart it.

Troubleshooting

Connecting takes several seconds, or output lags

On a mesh VPN (Tailscale and the like) a phone on cellular often reaches the server through a relay rather than directly, with a round trip of half a second or more. Everything still works; it is the network. See Tailscale and private networks for how to tell and what fixes it.

"tmux handshake timed out"

Sigmux attached but tmux did not answer in control mode within a few seconds. Usual causes: a tmux older than 3.2 on a host set to Control mode (switch the host to Classic attach), or a shell startup script that prompts for input (an updater, a license notice) before tmux can run. Sigmux waits for the shell to go quiet, but a script that keeps asking wins.

The keyboard will not appear, or appears over a sheet

Tap the terminal itself; scrolling and the key row's action keys are designed not to raise it. If it stays up over a sheet, close the sheet and drag down on the terminal.

Duplicated prompt lines in the scrollback

Some shells repaint the prompt on every resize and tmux pushes the old copy into history. set -g scroll-on-clear off in ~/.tmux.conf stops it.

A window shows an old screen after switching

Switching captures the window from tmux; if it looks stale, switch away and back to capture again. If it keeps happening, record a trace (below) and write to us.

Notifications stopped

Check Settings → Agents still shows the host as installed and send a test notification. If the trial ended, notifications pause until the purchase; removing hooks still works.

Recording a trace for a bug report

Settings → About → Runtime trace (session and tmux internals) or Terminal trace (rendering and keyboard sizing) write log files to the app's Documents folder, visible in the Files app under Sigmux. Reproduce the problem, turn the trace off, and send the file with a description of what you did. The files record control sequences, sizes and timings; with the byte payload option off they do not include what you typed.

Contact

Questions, bugs and feature requests: hezj07@gmail.com. How your data is handled is in the Privacy Policy.