Skip to content
ikazreal21Public

About

A free, local-first Android SSH terminal. terminuke keeps saved hosts and SSH keys on your device; it has no account, cloud sync, ads, or telemetry.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

terminuke

A free, local-first Android SSH terminal. terminuke keeps saved hosts and SSH keys on your device; it has no account, cloud sync, ads, or telemetry.

Early development: the debug APK builds, but has not yet been exercised on a physical Android device or against a real SSH server. Review docs/manual-test-checklist.md before relying on it for important connections.

Preview

terminuke host archive preview

Vector preview based on the supplied device screen.

What it does

  • Save, edit, search, and remove SSH hosts locally.
  • Connect with a one-time password, an imported or generated SSH key, or keyboard-interactive prompts such as an OTP.
  • Verify server host keys on first use. Review the SHA-256 fingerprint before choosing Trust once or Trust always; changed pinned keys are rejected.
  • Use an xterm/VT terminal with a touch-key row, copy/paste, scrollback, font sizing, and PTY resizing.
  • Generate Ed25519 and RSA-3072 keys or import PEM/OpenSSH private keys. Private key files are encrypted with AES-GCM using Android Keystore keys.
  • Export/import hosts as JSON. Passwords and private key material are not included.
  • Keep an active SSH connection in a foreground service with an ongoing notification and Disconnect action.

The MVP is single-session and Android-only. The host archive uses warm paper and graphite surfaces; the live terminal stays dark for contrast. SFTP, port forwarding, multiple tabs, cloud sync, and hardware security keys are not included.

Requirements

  • Android Studio (recent stable version) or Gradle command line.
  • JDK 17. The pinned Android Gradle Plugin 8.5.2 and Gradle 8.7 wrapper are tested with JDK 17; newer JDKs may not work with this toolchain.
  • Android SDK Platform 34 and Android Build Tools 34.
  • Android 8.0 (API 26) or newer to install; testing is intended on Android 14 or newer.

No API keys, cloud services, environment variables, or database server are required. Android Studio will create local.properties for the local SDK path; it is ignored by Git.

Build the debug APK

Open this directory in Android Studio, let Gradle sync, then select Build → Build Bundle(s) / APK(s) → Build APK(s).

Or use the Gradle wrapper from this project root:

./gradlew :app:assembleDebug

On Windows, use gradlew.bat :app:assembleDebug. If Gradle picks a different JDK, set Android Studio's Gradle JDK to JDK 17 or set JAVA_HOME before invoking the wrapper.

The installable debug APK is written to:

app/build/outputs/apk/debug/app-debug.apk

Install it over USB with Android Platform Tools (adb) if desired:

adb install -r app/build/outputs/apk/debug/app-debug.apk

Debug APKs use the local debug signing key generated by Android Gradle Plugin. That key is for development only, not for publishing an update to a store.

Build the v1.0 release APK

The app version is 1.0 (versionCode 1). Build the optimized release variant with:

./gradlew :app:assembleRelease

The signed release APK is written to:

app/build/outputs/apk/release/app-release.apk

Release signing is read from the local file named by TERMINUKE_SIGNING_PROPERTIES; if that variable is unset, Gradle looks for ignored app/release-signing.properties. This workspace keeps its release key and properties in the user config directory outside the repository. To build with that key on this machine:

TERMINUKE_SIGNING_PROPERTIES="$HOME/.config/terminuke/release-signing.properties" ./gradlew :app:assembleRelease

Never upload the keystore or signing properties to GitHub; back them up securely because future APK updates must use the same key. A fresh clone without release signing material can still build, but its release APK will be unsigned and Android will not install it until signed.

This v1.0 release key is different from Android Studio's debug key. To move from an already-installed debug build to the release build, export the hosts first, uninstall the debug app, install the release APK, then import the hosts. Keep private keys separately so they can be re-imported.

For later app releases, keep the same private keystore and increment versionCode in app/build.gradle.kts. To share this build on GitHub, attach only app-release.apk to a release tagged v1.0; do not include .p12 or release-signing.properties.

Test and lint

./gradlew testDebugUnitTest
./gradlew :app:lintDebug

The app unit tests currently cover host validation. The vendored Termux terminal-emulator unit tests run as part of testDebugUnitTest. Device/SSH integration testing is manual for now; use docs/manual-test-checklist.md.

Try an SSH connection

  1. Make an SSH server reachable from the Android device (for example, a Linux machine on the same Wi-Fi network).
  2. Open terminuke, choose Add host, and enter its address, port, and username.
  3. Choose password, saved-key, or keyboard-interactive authentication.
  4. On first connection, compare the displayed server fingerprint with a trusted source before accepting it.
  5. Try simple commands first (pwd, ls), then test full-screen tools such as vim or htop.

For the Android emulator, localhost refers to the emulator itself. Use the emulator host gateway (commonly 10.0.2.2) for a service running on the development computer. On a physical phone, use the computer/server's LAN address and ensure the network/firewall allows SSH.

Tinker with the code

The project is Kotlin with Jetpack Compose. App code is under app/src/main/java/com/terminuke/app/:

Area Location Purpose
UI MainActivity.kt Host, key, settings, trust, and terminal screens
Data data/ and data/db/ Room host/key/known-host data and DataStore settings
SSH ssh/ SSHJ transport, authentication, host-key validation, session state
Terminal terminal/ Compose AndroidView bridge to the terminal emulator
Encryption crypto/ Android Keystore AES-GCM key-file storage
Foreground lifecycle service/ Ongoing SSH notification and disconnect action
Validation domain/HostValidator.kt Pure Kotlin host input rules and unit tests

Dependency versions are centralized in gradle/libs.versions.toml. Room schema snapshots are kept in app/schemas/; update and commit them when changing Room entities or database versions. The Gradle wrapper files are deliberately tracked so contributors use the same Gradle release.

The terminal emulator and view are vendored in third_party/termux/ to make builds reproducible. Their Apache-2.0 license and attribution are in that directory. TerminalSession.java has a small terminuke adapter for remote SSH streams; third_party/termux/NOTICE.md records the upstream commit and local changes.

Security and data

  • Host addresses and connection preferences are stored locally in Room/DataStore. Hostnames are not encrypted in the database.
  • Private keys are stored in app-private files after AES-GCM encryption with keys managed by Android Keystore. Android automatic backup is disabled.
  • SSH passwords and keyboard-interactive responses are not saved. A password or challenge response is only used for the active connection.
  • First-use host-key trust is a security decision: verify the fingerprint independently. A changed pinned key fails closed.
  • Terminal screenshots/Recents protection is an optional setting. Clipboard copy shows a reminder that copied text may remain in keyboard/clipboard history.
  • Do not put real private keys, passwords, signing keys, SDK paths, or machine-specific configuration into the repository. .gitignore excludes common local secret/signing files.

Known limitations

  • The current version has not yet had a real-device/SSH-server acceptance pass. Terminal IME behavior, key-provider compatibility, Android foreground service behavior, and PTY resizing still need manual testing.
  • Generated keys are encrypted at rest by the app, but are not additionally protected by a key passphrase at generation time. Passphrase-protected imported keys can be unlocked when connecting.
  • Imported key public-key preview and PuTTY .ppk conversion are not implemented.
  • There is no favorite toggle or full connection-history screen; hosts are ordered partly by most recent connection.
  • The connection does not automatically restore after the app process is killed.
  • See docs/v2-backlog.md for deliberately deferred features and docs/manual-test-checklist.md for verification steps.

License

terminuke is licensed under the MIT License. Vendored Termux terminal components have their own Apache-2.0 license and attribution; see third_party/termux/.

About

A free, local-first Android SSH terminal. terminuke keeps saved hosts and SSH keys on your device; it has no account, cloud sync, ads, or telemetry.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages