Resumable Mobile SSH with neosh

1. Scope: This Is an iPad Usage + Deployment Note

This note covers practical usage of neosh with NeoShell on iPad.

It covers:

• enabling neosh in the NeoShell client
• deploying neoshd on your server
• understanding how NeoShell manages resumable sessions

2. How to Enable neosh on iPad (NeoShell)

2.1 Edit Host Profile

In Host settings, set Transport to neosh. NeoShell has an explicit transport selector (SSH / neosh) in the profile editor.

2.2 Keep Normal Auth Inputs

Use your usual host, username, and password or SSH key in the same profile. NeoShell handles the bootstrap sequence for neosh in the background.

2.3 Connect Normally from iPad

NeoShell includes a built-in neosh client runtime, so no additional tools are required on iPad.

3. Server Deployment: Install neoshd

3.1 Install neoshd on Remote Host

Use the upstream install script:

curl -fsSL https://raw.githubusercontent.com/plucury/neosh/main/scripts/install_neoshd.sh | bash

Or install to a custom directory:

INSTALL_DIR="$HOME/.local/bin" curl -fsSL https://raw.githubusercontent.com/plucury/neosh/main/scripts/install_neoshd.sh | bash

3.2 Verify Binary and PATH

command -v neoshd
neoshd version

NeoShell checks neoshd availability during bootstrap. If it is not found in PATH, the app reports neoshd not installed.

3.3 Network Prerequisites

Keep SSH reachable for bootstrap, and allow the QUIC endpoint returned by neoshd. In default bootstrap-style binding, upstream docs indicate dynamic ports in the 30000-39999 range, so firewall policy must permit that UDP traffic.

neosh uses QUIC (UDP), so the returned endpoint must be reachable from the client network.

4. What NeoShell Actually Does on iPad

4.1 SSH Bootstrap First, Then QUIC Session

In NeoShell's implementation, neosh connection starts with an SSH bootstrap step to locate and run neoshd, obtain bootstrap JSON, then establish QUIC using the returned endpoint and fingerprint.

4.2 Resume Is Built Into App Flow

NeoShell stores neosh resume state per host (session_id + resume_token) and attempts renew-auth + resume on reconnect before creating a fresh session.

This avoids creating a fresh shell on every reconnect.

4.3 iPad UX Impact

This is why neosh mode generally behaves better under mobile network changes: reconnect is more likely to restore the existing session context instead of dropping users into a brand-new shell.

This allows the app to recover sessions after short mobile network interruptions.

5. Common Issues

5.1 Error: neoshd not installed

Install neoshd on the server and reconnect. NeoShell also provides a fallback action to switch that host transport back to standard SSH.

5.2 Error: Endpoint / Auth Failed

Verify server-side neoshd bootstrap, returned endpoint reachability, and token freshness. If you need an immediate workaround, switch transport to SSH first.

5.3 Firewall Blocking UDP

If QUIC ports are blocked, neosh cannot establish the session transport. Keep SSH bootstrap reachable and allow the returned QUIC UDP endpoint.

6. Deployment Checklist (Recommended)

• Install neoshd and ensure it is in PATH for the target user.
• Verify neoshd version returns successfully.
• Allow SSH bootstrap and QUIC endpoint traffic in firewall/security groups.
• In NeoShell Host settings, switch Transport to neosh.
• Run real mobile tests: lock/unlock, Wi-Fi to cellular switch, short network drop.

7. Reference

Project repository: github.com/plucury/neosh