iOS Setup

This guide walks you through installing RemoteConsoleSSH on your iPhone or iPad, setting up app security, and connecting to your first SSH server.

Requirements

iPhone or iPad running iOS 16 or later
An SSH-enabled remote machine (see prerequisites)
Network connectivity to the remote machine (local Wi-Fi, VPN, or Tailscale)

Install the App

Download RemoteConsoleSSH from the App Store. Search for "RemoteConsoleSSH" or use the direct link from the home page.

First Launch Setup

When you open the app for the first time, you will be guided through setting up app security. This protects your saved connections and credentials.

Set a PIN code

You will be prompted to create a numeric PIN. This PIN is required every time you open the app. Choose something memorable but not easily guessed — the PIN is hashed with SHA-256 before being stored on your device.

Enable biometric authentication (optional)

After setting your PIN, the app will ask if you want to enable Face ID or Touch ID. This is optional but strongly recommended — it lets you unlock the app with a glance or a fingerprint instead of typing your PIN every time.

💡

Tip

You can always change your PIN or toggle biometric authentication later in Settings.

You are on the home screen

After setup, you land on the connections screen. It will be empty since you have not added any servers yet. Time to add your first connection.

Add Your First Connection

Tap the "+" button

On the home screen, tap the add button to open the connection form.

Enter connection details

Fill in the following fields:

Name — A label for this connection (e.g., "My MacBook" or "Dev Server"). This is just for your reference.
Hostname or IP — The address of the remote machine. This could be an IP address like 192.168.1.100, a Tailscale hostname like my-macbook, or a fully qualified domain name.
Port — The SSH port. The default is 22. Only change this if your server uses a non-standard port.
Username — Your user account on the remote machine.

Choose an authentication method

You have two options:

Password — Enter the password for your user account on the remote machine. The password is stored securely in the iOS Keychain.
SSH Key — Paste your private key directly into the text field, or tap the import button to select a key file from the Files app. If your key is passphrase-protected, you will be prompted to enter the passphrase.

💡

Tip

SSH key authentication is more secure and eliminates the need to type a password on each connection. If you have not set up SSH keys yet, see the SSH key guide.

Save the connection

Tap Save. Your new connection appears on the home screen.

Connect and Verify

Tap the connection

On the home screen, tap the connection you just created.

Accept the host key (first connection only)

The first time you connect to a server, the app displays the server's host key fingerprint and asks you to verify it. This is a security measure to prevent man-in-the-middle attacks. Confirm that the fingerprint matches your server's key, then tap Accept.

ℹ️

Info

The host key is saved after you accept it. Future connections to the same server will not prompt you again unless the server's key changes (which could indicate a security issue).

You are connected

You should see a terminal prompt. Try running a command to verify everything works:

echo "Hello from RemoteConsoleSSH"

If you have tmux installed on the remote machine, the app automatically creates or attaches to a persistent session. You will see a tmux status bar at the bottom of the terminal.

iOS-Specific Features and Notes

Keyboard Toolbar

The iOS keyboard includes a toolbar above the standard keyboard with quick access to keys that are commonly needed in a terminal but missing from the default iOS keyboard:

Special keys: Esc, Tab, Ctrl, arrow keys (up, down, left, right)
Pipe and symbols: |, /, ~, -
Microphone button: Tap to activate voice control mode

The toolbar scrolls horizontally if needed, so swipe to find additional keys.

Voice Control

Tap the microphone button in the keyboard toolbar to use voice commands. You can speak naturally and the app translates your speech into terminal commands. For example:

"list all files" runs ls -la
"go to home directory" runs cd ~
"git status" runs git status

Grant microphone permission when prompted on first use. See the voice control guide for the full list of supported commands.

Background Behavior

iOS suspends apps shortly after you switch away from them. RemoteConsoleSSH requests a brief background execution window to keep your SSH connection alive when you quickly switch to another app and back. However, if you leave the app in the background for an extended period, the connection will be dropped.

💡

Tip

This is where tmux becomes essential. If the connection drops while the app is in the background, RemoteConsoleSSH automatically reconnects and reattaches to your tmux session when you return — so you never lose your work. Make sure tmux is installed on your server.

Secure Storage

All connection credentials (passwords, SSH private keys, PINs) are stored in the iOS Keychain, Apple's hardware-backed secure storage. They are never written to disk in plaintext and are protected by your device's Secure Enclave.

Troubleshooting

Connection times out

Verify that the remote machine's SSH server is running.
Check that your device can reach the remote machine's IP address. If you are using Tailscale, make sure it is connected on both devices.
Confirm the port number is correct (default: 22).

Authentication fails

Double-check your username and password or SSH key.
If using an SSH key, ensure the corresponding public key is in the remote machine's ~/.ssh/authorized_keys file.
If using a passphrase-protected key, verify the passphrase is correct.

Terminal looks garbled

The terminal expects UTF-8 encoding. Ensure your server's locale is set to a UTF-8 locale (e.g., en_US.UTF-8).
Try running reset to clear the terminal state.