Common Issues & FAQ

Solutions to the most common problems you might encounter when using RemoteConsoleSSH.

Connection Issues

"Connection refused" when trying to connect

This usually means the SSH server isn't running on the target computer, or a firewall is blocking the connection.

1. SSH is not enabled on the target computer. Follow the Enable Remote Login guide to turn it on.

2. Wrong port. The default SSH port is 22. If your server uses a different port, make sure you've set it correctly in your connection settings.

3. Firewall blocking SSH. Your computer's firewall may be blocking incoming SSH connections. See the firewall sections in the Remote Login guide.

4. Wrong hostname or IP address. Double-check the address:

   • Local network: use hostname.local (macOS) or your local IP (192.168.x.x)
   • Tailscale: use the Tailscale hostname or 100.x.x.x address
   • Run tailscale status on your computer to verify the address

5. Computer is asleep or powered off. SSH can't connect to a sleeping computer. On macOS, enable "Wake for network access" in System Settings → Energy.

"Connection timed out"

The app can reach the network but not your specific computer.

• Different networks: Your phone and computer must be on the same network (or connected via Tailscale/VPN). You cannot SSH to a home computer from a coffee shop WiFi without Tailscale or port forwarding.
• Tailscale not running: If using Tailscale, make sure it's active on both devices. Check the Tailscale icon in your status bar/system tray.
• Router/NAT issues: If using port forwarding, verify the port forward is active in your router settings.

"Host key verification failed"

This happens when the server's host key has changed since your last connection — usually after reinstalling the OS or SSH server.

To fix: delete the saved connection in RemoteConsoleSSH and add it again. The app will prompt you to accept the new host key on the next connection.

If connecting from a terminal: ssh-keygen -R hostname removes the old key.

Authentication Issues

"Authentication failed" with password

• Wrong password. SSH passwords are case-sensitive. Try typing it slowly.
• Password auth disabled. Some servers disable password authentication. Check /etc/ssh/sshd_config on the server for PasswordAuthentication yes.
• Wrong username. Verify you're using the correct username. On macOS, this is usually your short username (run whoami to check).
• Account locked. Too many failed attempts may lock the account. Wait a few minutes or check the server logs: sudo cat /var/log/auth.log (Linux) or log show --predicate 'process == "sshd"' --last 5m (macOS).

"Authentication failed" with SSH key

• Wrong key format. RemoteConsoleSSH expects the OpenSSH private key format (starts with -----BEGIN OPENSSH PRIVATE KEY-----). If your key is in PuTTY format (.ppk), convert it: ssh-keygen -i -f key.ppk > key_openssh.
• Key not added to server. Your public key must be in ~/.ssh/authorized_keys on the server. See the SSH Keys guide.
• File permissions too open. SSH refuses to use keys with wrong permissions. On the server:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

• Passphrase-protected key. If your key has a passphrase, make sure you enter it when prompted in the app.

"Permission denied (publickey)"

The server only accepts key-based authentication and doesn't recognize your key.

1. Verify your public key is in ~/.ssh/authorized_keys on the server
2. Check that the key type is supported (ed25519 or RSA)
3. Debug from a terminal: ssh -v user@host — look for "Offering public key" messages

Connection Drops & Reconnection

Connection drops frequently

• Unstable network. Mobile networks (cellular, weak WiFi) cause frequent drops. Use a stable WiFi connection when possible.
• Server timeout. The SSH server may close idle connections. Add to the server's /etc/ssh/sshd_config:

ClientAliveInterval 60
ClientAliveCountMax 3

Then restart SSH: sudo systemctl restart sshd

• Phone going to sleep. iOS and Android aggressively suspend background apps. This is normal — with tmux, your session is preserved and the app will reconnect automatically.

"Reconnecting..." stays on screen

The app is trying to reconnect with exponential backoff (2s, 4s, 8s, 16s, 32s). If it fails after 5 attempts:

1. Check that your computer is still on and connected to the network
2. Check that Tailscale (if used) is still active
3. Try manually disconnecting and reconnecting
4. If the problem persists, close and reopen the app

Terminal Display Issues

Text or special characters look wrong

• Font rendering. The app uses JetBrains Mono which has excellent Unicode coverage. If characters still look wrong, the issue is likely the server's locale settings.
• Locale not set. Make sure the server has UTF-8 locale configured:

# Check current locale
locale
 
# If not UTF-8, set it
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

Add these to your ~/.bashrc or ~/.zshrc to make them permanent.

Spinners, progress bars, or TUI apps render incorrectly

• Terminal size mismatch. The app sends terminal dimensions to the server, but rotating your phone or resizing may cause a brief mismatch. The terminal auto-resizes — wait a moment or tap the refresh button.
• TERM variable. RemoteConsoleSSH sets TERM=xterm-256color. If a specific app doesn't render correctly, try: export TERM=xterm

Colors not showing

The terminal supports 256 colors. If you see no colors:

• Check that TERM=xterm-256color is set (run echo $TERM)
• Some programs need color explicitly enabled (e.g., ls --color=auto, grep --color=auto)

Voice Control Issues

Voice control button not appearing

• Voice control is only available on iOS and Android native apps — not on the web version.
• Make sure you have the latest version of the app installed.

Speech not being recognized

• Microphone permission denied. Check your device settings:
  • iOS: Settings → RemoteConsoleSSH → Microphone (must be enabled)
  • Android: Settings → Apps → RemoteConsoleSSH → Permissions → Microphone
• Noisy environment. Speech recognition works best in quiet environments. Speak clearly and at a normal pace.
• Language. The speech recognizer uses your device's language setting. For best results, use English.

Commands are interpreted incorrectly

• The AI command interpreter may misinterpret ambiguous speech. Try being more specific:
  • Instead of "go there" → "go to the downloads folder"
  • Instead of "show it" → "show the file contents"
• Switch to Text mode if you want exact transcription without AI interpretation.
• Check your AI provider settings in Settings → Voice. Try a different provider if results are poor.

Platform-Specific Issues

iOS

• App killed in background. iOS aggressively manages background apps. This is expected — with tmux, your server session is preserved. Just reopen the app to reconnect.
• Keyboard covers terminal. Scroll up in the terminal to see hidden content, or rotate to landscape mode for more vertical space.
• Biometric auth not working. Go to Settings → Security and re-enable Face ID / Touch ID. Make sure biometrics are set up in iOS Settings → Face ID & Passcode.

Android

• Battery optimization killing the app. Go to Settings → Apps → RemoteConsoleSSH → Battery → Unrestricted to prevent Android from killing the app in the background.
• Microphone permission not saving. Some Android skins require granting the permission through the system settings rather than the in-app prompt.

Web

• Session lost when closing tab. The web version does not maintain connections when the tab is closed. Use the native app for persistent connections.
• Keyboard shortcuts intercepted by browser. Some shortcuts (Ctrl+W, Ctrl+T, etc.) are captured by the browser instead of being sent to the terminal. Use the keyboard toolbar for these keys.
• No clipboard access. Some browsers block clipboard access. Use Chrome for the best experience with copy/paste.

Frequently Asked Questions

Is RemoteConsoleSSH free?

The app is free to download and use with full functionality.

What SSH protocols does it support?

RemoteConsoleSSH uses the dartssh2 library which supports modern SSH protocols including AES-256-CTR, ChaCha20-Poly1305 for encryption and ed25519, RSA for authentication.

Can I connect to servers other than my own computer?

Yes. RemoteConsoleSSH connects to any SSH server — your personal computer, cloud VPS (AWS, DigitalOcean, etc.), Raspberry Pi, or any other SSH-accessible machine.

Does it support SSH tunneling / port forwarding?

Not currently. The app focuses on terminal access, file transfer, and voice control.

Can I use it without Tailscale?

Absolutely. Tailscale is recommended for ease of use, but you can connect over any network — local WiFi, port forwarding, other VPNs, or direct public IP.

Where are my credentials stored?

• iOS: Keychain Services (hardware-encrypted)
• Android: EncryptedSharedPreferences (AES-256)
• Web: Browser localStorage (less secure — avoid storing sensitive credentials)

Your PIN is hashed with SHA-256 before storage. Private SSH keys are stored in the platform's secure storage.

Can multiple devices connect to the same tmux session?

Yes. If you have tmux running on the server, you can connect from your phone, tablet, and desktop simultaneously. All devices see the same terminal in real-time.