SSH Tunnel Documentation

Overview

SSH Tunnel connects your device to your own SSH server and routes traffic through it. It covers the same jobs as the OpenSSH command-line client's tunneling flags: a dynamic SOCKS5 proxy (ssh -D) and local port forwarding (ssh -L) — with no jailbreak, no terminal and no third-party servers involved. It can also act as a full VPN, sending all of the device's traffic through your server.

The app runs on iPhone, iPad and Mac (menu bar app). One purchase covers all three.

Getting started

1. Add a connection. Tap + and enter your server's host name or IP address, SSH port (usually 22) and user name.
2. Pick an authentication method: password, private key or a 2FA verification code. See Authentication.
3. Pick an engine. New connections use the VPN engine by default; see Choosing an engine for when the Proxy engine is the better fit.
4. Connect. Flip the connection's toggle. On the first connect the app shows the server's host key fingerprint for you to confirm; with the VPN engine, iOS/macOS also asks once for permission to add a VPN configuration.
5. Verify it works. Open an IP-echo site such as ifconfig.me. It should show your SSH server's IP address, not your own.

Choosing an engine: VPN vs Proxy

Every connection runs on one of two engines. Which one you pick decides what the tunnel covers and whether it keeps running in the background — it is the most important setting in the app.

Which engine for which job

• “I want everything on my phone to go through my server — including cellular, with the screen locked.” VPN engine. This is the right choice for most people.
• “I just want to browse through my server on this device.” VPN engine — nothing to configure. (The Proxy engine plus a PAC file also works if you prefer to route only Safari on Wi-Fi.)
• “I want my laptop or iPad to use my phone's tunnel over Wi-Fi or hotspot.” Proxy engine, bound to 0.0.0.0. The VPN engine cannot share.
• “I need to reach one internal service — RDP, VNC, a database, a router panel.” Proxy engine with a static forward, the ssh -L analog.
• “The tunnel should come back by itself after a reboot or network change.” VPN engine with On Demand enabled.

You can run the VPN engine and Proxy-engine tunnels at the same time; the proxy connection simply rides through the VPN.

Authentication

Password

Stored in the device Keychain, never in plain files.

Private keys

The app accepts OpenSSH keys (ed25519, ECDSA, RSA) and PuTTY .ppk keys, with or without a passphrase. Paste the key text or import the file. Keys and passphrases are stored in the Keychain.

2FA verification codes

For servers that ask for a one-time code (keyboard-interactive authentication, e.g. Google Authenticator TOTP), enable Ask for verification code on the connection. The app prompts for the code each time you connect, before the connection starts — including for VPN-engine connections.

Host key verification

On the first connect the app shows the server's host key fingerprint; confirm it matches your server. If the key later changes, the app warns you and refuses to connect until you accept the new key — verify the change with your server admin first, since it can also mean someone is intercepting the connection.

The VPN engine

The VPN engine registers a standard system VPN configuration and routes all device traffic through your SSH server — every app, on Wi-Fi and cellular. The VPN icon appears in the status bar while connected.

• Background operation. The tunnel keeps running with the app in the background, with the screen locked, and even after you close the app.
• VPN On Demand. With On Demand enabled, the system re-establishes the tunnel automatically — after a reboot, a network change or a dropped connection.
• One VPN at a time. The system allows a single active VPN, so one VPN-engine tunnel runs at a time (Proxy-engine tunnels can run alongside it).
• 2FA connections. A connection that asks for a verification code cannot reconnect unattended — there is no way to answer a code prompt in the background. If such a tunnel drops, the app sends a notification with a Reconnect action that reopens the code prompt.

The Proxy engine

The Proxy engine runs the tunnel inside the app and opens local listeners, exactly like the OpenSSH client's forwarding flags. On iOS it works while the app is in the foreground; on the Mac it runs as long as the menu bar app is up.

Dynamic — SOCKS5 proxy (the ssh -D analog)

A dynamic connection opens a SOCKS5 proxy on your device, equivalent to:

ssh -D 1080 user@your-server

Point any app that supports SOCKS at the address shown on the connection screen (for example 127.0.0.1:1080), and its traffic goes through your server.

PAC file — configuring Wi-Fi to use the proxy

The app serves a proxy auto-configuration (PAC) file so iOS itself can use the tunnel: on the connection screen, copy the PAC URL, then in Settings → Wi-Fi → (i) → Configure Proxy → Automatic paste it. Safari and most apps on that Wi-Fi network then use the proxy. Remember to switch the setting back to Off when you disconnect.

Sharing the tunnel with other devices

Set the bind address to 0.0.0.0 — the analog of:

ssh -D 0.0.0.0:1080 user@your-server

The connection screen then shows your device's Wi-Fi IP address; other devices on the same network (a laptop, an iPad, a TV) can use it as their SOCKS proxy or PAC URL. Works over a personal hotspot too.

Static — local port forwarding (the ssh -L analog)

A static connection forwards one local port to one destination behind the server, equivalent to:

ssh -L 3389:192.168.1.20:3389 user@your-server

With that example connected, an RDP client pointed at 127.0.0.1:3389 reaches the Windows machine at 192.168.1.20 on the server's network. The same pattern covers VNC, databases, web panels — anything TCP. Several static tunnels can run at once on distinct local ports.

In-app browser

The globe button on the connection screen opens a built-in browser that uses the tunnel directly — handy on iOS since the Proxy engine only runs while the app is in the foreground.

SSH Tunnel on the Mac

The Mac version lives in the menu bar (no Dock icon) and runs tunnels for as long as it is open — the foreground-only limitation is an iOS one.

• VPN engine: works exactly as on iOS and is the zero-configuration way to route the whole Mac through your server.
• Proxy engine: macOS does not let sandboxed apps change the system proxy, so copy the address from the connection window (for example 127.0.0.1:1080) into System Settings → Network → Wi-Fi → Details → Proxies → SOCKS proxy, or configure individual apps to use it.

Troubleshooting

Is my traffic really going through the server?

Open an IP-echo site such as ifconfig.me in the browser you routed. It should print the SSH server's IP address.

The tunnel drops when I switch apps or lock the screen

That is the Proxy engine on iOS: the system suspends the app about 30 seconds after it leaves the foreground. Switch the connection to the VPN engine, which keeps running in the background.

“Unable to bind” / address already in use

Another program — or a previous tunnel that has not fully closed yet — occupies the local port. Change the connection's local port, or wait a moment and reconnect.

Key authentication fails

Check that the key is a supported format (OpenSSH or PuTTY .ppk) and the passphrase is right. When pasting a key, make sure the text is complete — including the header, footer and the final line break; a key pasted without its trailing newline fails to parse.

Host key changed warning

The server presents a different host key than the one you accepted before. This is expected after a server reinstall or key rotation — confirm with the server's admin, then accept the new key. If nothing changed on the server, treat it as a possible interception and do not connect.

A leak-test site shows my real IP in the in-app browser

Web pages can open connections that bypass an app-level proxy (DNS prefetching and similar browser side channels). The VPN engine routes at the network level, so nothing bypasses it — use the VPN engine when you need leak-free browsing.

The tunnel disconnects by itself after a while

Check the connection's inactivity auto-disconnect setting — with a timeout set, the tunnel closes after that long without traffic. Set it to off for an always-on tunnel.

FAQ

Does SSH Tunnel work in the background?

Yes. Connections on the VPN engine keep running with the app in the background, with the screen locked, and after the app is closed. The Proxy engine is foreground-only on iOS.

Can it route all my apps through the server, system-wide?

Yes. The VPN engine routes all device traffic — every app — through your SSH server, on Wi-Fi and cellular.

Does it work on cellular?

Yes, the VPN engine works on any network. The Proxy engine's Wi-Fi PAC setting applies only on Wi-Fi, but the SOCKS proxy itself is available to apps on any network.

Does it support two-factor authentication (2FA)?

Yes. Enable “Ask for verification code” on the connection and the app prompts for your one-time code before connecting.

Can I use PuTTY (.ppk) keys?

Yes. The app accepts PuTTY .ppk and OpenSSH private keys — ed25519, ECDSA and RSA, with or without a passphrase.

Does it support remote port forwarding (ssh -R)?

No. The app covers dynamic SOCKS5 forwarding (ssh -D) and local port forwarding (ssh -L). Remote forwarding (ssh -R) is not supported.

Is my traffic private?

Your traffic goes to your own SSH server — there are no third-party servers in between, and the app does not collect or sell traffic data. See the privacy policy.

Is there a Mac version?

Yes — a menu bar app with the same engines. One purchase covers iPhone, iPad and Mac.