Troubleshooting and FAQ

Frequently Asked Questions and Troubleshooting

Find quick solutions for common questions, background service persistence, battery optimizations, security guarantees, and workflow edge cases across Casshper.

Hardware Keystore and Key Security

Q: Are my private keys exported or backed up to cloud services?

No. Keys generated inside Android's Hardware Keystore (TEE) are cryptographically bound to your physical device. Private key material never touches the regular filesystem, cannot be exported, and is never synced to external cloud services or telemetry endpoints.

Q: Can I use password-encrypted SSH private keys?

Yes. When authenticating with an encrypted private key file, Casshper prompts for your passphrase during session initialization and securely authenticates directly over SSH.

Q: How are SSH host key fingerprints verified?

When connecting to a new host for the first time, Casshper prompts you to verify and accept the host's public SSH key fingerprint. Known host fingerprints are stored securely in your device's local application storage.

SFTP Mounting and System Storage (SAF)

Q: Why doesn't my mounted drive appear in some third-party Android apps?

Some legacy Android applications do not support Android's Storage Access Framework (SAF) system picker. Ensure the application supports opening documents via the native Android document picker (SAF).

Q: What happens if my mobile network drops while editing a file?

Casshper buffers file modifications safely. When you save or retry the file transfer, Casshper re-establishes the SFTP connection handle over SSH to commit your changes back to the remote server.

Port Forwarding and Networking

Q: Why can't I connect to 127.0.0.1:8080 in Chrome on Android?

Ensure that port forwarding is started via your host's options menu (select Start Forwarding). If another Android application is already using port 8080, change the local source port (e.g., 8085) in Manage Ports to prevent port collisions.

Q: Do port forwarding tunnels work while the app is in the background?

Yes. Tunnels run as a persistent foreground service with a status bar notification. Make sure Battery Optimization is set to Unrestricted so Android does not kill the SSH socket daemon.

Q: Does session persistence keep my terminal connected across network changes or Wi-Fi drops?

No. Session persistence in Casshper is specifically focused on Android app lifecycle management—preventing Android from killing your active local shell or long-running jobs when swapping between apps. Casshper connects over standard SSH (TCP) and does not use roaming protocols like mosh. If your Wi-Fi or cellular connection drops, the TCP socket will close. To preserve remote jobs across network changes, run a remote multiplexer such as tmux or screen.

Touch Gestures, Sneaky Input and Terminal Control

Q: How do I draft multiline SQL queries or long commands without touchscreen typos?

Use Sneaky Input (triple-tap the terminal surface or trigger via gesture). It opens a native Android text container supporting swipe typing, voice-to-text dictation, and clipboard staging before sending your text atomically to the active shell session.

Q: Why doesn't a single swipe trigger a gesture action?

Raw single swipes from rest are intentionally reserved for scrolling the terminal canvas. Gesture swipes require a preceding tap or long-press sequence (such as Tap → Tap → Swipe Left) to prevent accidental execution while scrolling.

Q: How do I reset touch gestures to factory defaults?

Open the sidebar menu, select Settings, switch to the Touch Gestures tab, and tap Reset Gestures to Default to restore standard out-of-the-box tap and swipe shortcuts.

Terminal Emulation and SSH Terminfo (xterm-ghostty)

Q: Why do I see “missing or unsuitable terminal: xterm-ghostty” when connecting over SSH?

Casshper is powered by the Ghostty engine and advertises TERM=xterm-ghostty. While Ghostty’s terminfo definition is included in upstream ncurses (version 6.5-20241228 and newer), older server distributions often lack this definition. When connecting to such servers, terminal programs like Vim, Neovim, tmux, or htop may report terminal errors or fail to render properly.

Q: How do I copy Ghostty’s terminfo entry to a remote server?

You can export and compile the xterm-ghostty definition directly onto your remote server with a single command from your local terminal:

infocmp -x xterm-ghostty | ssh YOUR-SERVER -- tic -x -

This command extracts the compiled terminfo from your local environment using infocmp and pipes it to tic on the server, which compiles it into /usr/share/terminfo (if running with write permissions) or $HOME/.terminfo (for unprivileged users). Any warning from older tic versions treating the description field as an alias can be safely ignored.

Pure JS Runtime and Local AI Agents

Q: Can I run Node.js utilities or CLI tools without root access on Android?

Yes. Casshper bundles an embedded Node.js 22 runtime and Zsh shell. Pure JavaScript packages (such as pi AI coding agent, npm package utilities, or custom JS automation scripts) run 100% locally on Android without root or native C++ compilation.

Privacy Guarantee and Pro Admin Licensing

Q: Does Casshper require an internet connection or account sign-in to function?

No. Casshper is built on a 100% local, offline-first philosophy. All SSH connections, key generation, rendering, and Pro Admin features operate completely offline with zero telemetry, remote tracking, or mandatory account creation.

Q: Why didn't my home screen icon change immediately after selecting Monocle?

Some Android launchers (such as Pixel Launcher, Samsung OneUI, or Nova Launcher) cache app icons. Restarting your launcher or launching Casshper once from your app drawer will refresh the home screen icon.

Contact and Community Support

Q: How do I contact support or submit feature requests?

You can contact our team directly via the developer contact link on our official Google Play Store page or join the community discussion on Reddit at /r/Casshper!