Support & documentation

A little help.
Then back to work.

Connection setup, everyday workflows, and answers to the things that tend to get in the way.

Your first connection

  1. Open the host list and add a host. Enter its hostname or IP address, SSH port (usually 22) and username.
  2. Choose password or SSH-key authentication. To use a key, open SSH Keys to generate a Secure Enclave, Ed25519 or RSA key, or import an unencrypted OpenSSH private key.
  3. Add the public key to the server’s ~/.ssh/authorized_keys. Keep private keys private.
  4. Connect and compare the server’s host-key fingerprint with a value you obtained through a trusted channel before accepting it.

Mobilissh requires iOS or iPadOS 17 or later and an SSH server you are authorized to use. It provides remote SSH terminals, not a local iOS shell. No Mobilissh account is required.

Pick up your tmux workspace

On your server, run:

tmux -CC
# Or attach an existing session:
tmux -CC attach

tmux panes become native terminal surfaces and windows become tabs. Use the session menu or keyboard shortcuts to split panes, change windows or detach. tmux 3.2 or later is required; forwarding your tmux prefix bindings requires 3.4 or later.

To discover detached sessions at connection time, enable Offer tmux sessions on connect in the host editor. This runs a tmux session-discovery command on your server. Remote tmux sessions persist independently of the app while the server keeps them running.

Port forwarding and files

Configure forwards in Edit Host → Port Forwarding or the current session’s menu. A local forward listens only on your device’s loopback interface. For example, forward a device port to your server’s development service, then open http://localhost:PORT in Safari. A remote forward exposes a server-side localhost port to a destination reachable from your device.

Tap a file path in terminal output to download and preview it with Quick Look, then share it to Files or another app. File previews are limited to 200 MiB. Pasted images are limited to 50 MiB and go to your connected server, either as image data for compatible programs or as an uploaded file. See file handling and retention.

Troubleshooting & common questions

Why does my connection time out or get refused?

Check the host, port, network/VPN and server firewall. Confirm that SSH is running and reachable from your device’s network. Nearby discovery needs Local Network permission; discovering a service does not guarantee that authentication will succeed.

Why is my private key rejected?

Passphrase-protected private keys and SSH agent forwarding are not supported. Use an unencrypted OpenSSH key secured in the device Keychain, or generate a new key in the app. RSA authentication uses rsa-sha2-256/512; legacy SHA-1 ssh-rsa is not supported. Confirm the matching public key is installed for the correct server account.

The server host key changed. Should I accept it?

Do not accept an unexpected change without verifying the new fingerprint with your server administrator through a trusted channel. A change can be legitimate after a server rebuild, but it can also indicate an intercepted connection. Edit the host and use Forget Host Key only after verifying the server.

Why does a session disconnect in the background?

iOS can suspend the app after it leaves the foreground. Mobilissh attempts to reconnect dropped sessions when you return, but a clean remote exit is not reconnected. Use tmux for server-side persistence. The optional Keep connections alive in background setting uses location permission and may help keep connections and forwards running; it costs battery and is not a guarantee.

Why does the app request location access?

Only the optional background-connection setting uses location updates. Coordinates are not used, stored or transmitted by Mobilissh. You can leave this setting off and use foreground SSH normally. See the permissions explanation.

Can I recover a Secure Enclave key on another device?

No. Secure Enclave private keys cannot be exported or backed up, and saved credentials use device-only Keychain storage. Keep another authorized way to access your server before replacing or resetting your device.

Why are colors, keys or images different on my server?

The default terminal type is xterm-256color. Only use xterm-ghostty if the server has its terminfo installed. Kitty inline graphics are supported; Sixel and iTerm2 inline images are not. Images inside tmux need allow-passthrough enabled and may disappear on redraw. Desktop-only Ghostty config options do not apply to iOS.

Does Wake-on-LAN work on an iPhone or iPad?

It depends on the network and Apple’s restricted multicast permission for the build. Current builds may report that iOS blocked the broadcast. Do not rely on Wake-on-LAN as your only way to regain server access.

Where do I change themes, fonts or key bindings?

Open Settings to choose the theme, font and size, or edit the raw Ghostty-format configuration. Changes apply live on save. The Ghostty configuration reference describes the format; options requiring desktop windows or a local shell do not apply.

How do I delete my saved data?

Delete hosts from the host list and keys from SSH Keys. Use Forget Host Key separately for stored server trust. Delete keys and passwords in the app before uninstalling; uninstalling is not a guaranteed Keychain wipe. Remote uploads and shared files must be removed separately. The privacy policy lists the controls and limits.

Contact & bug reports

For a useful bug report, include:

  • Your Mobilissh version and build number from Settings → About.
  • Your device model and iOS or iPadOS version.
  • What you expected, what happened, and the steps to reproduce it.
  • The exact error message and, where relevant, your server’s SSH/tmux version.

Keep secrets out of support messages. Never send a private key, password or access token. Redact usernames, hostnames, IP addresses and confidential terminal output from screenshots and logs.

For Apple-managed purchases or refunds, use Apple’s Report a Problem service. App distribution and billing are handled under Apple’s applicable terms.