Skip to content
nimrcPublic

About

Bellterm: an Android client for Herdr daemons over SSH, with libghostty-vt as the terminal

Topics

Resources

Stars

8 stars

Watchers

0 watching

Forks

Repository files navigation

Bellterm

Bellterm is a native Android client for a Herdr daemon running on a machine you reach over SSH. The name is the terminal's bell (BEL) and the bellwether that leads a herd: it rings when an agent needs you. It is a client only: Herdr on the host owns the terminals, workspaces, tabs, panes, and agents, and they keep running when the phone disconnects, sleeps, or loses signal.

Unaffiliated project. Bellterm works with Herdr but is not affiliated with, endorsed by, or supported by Herdr or herdr.dev.

Bellterm runs on Android 10 (API 29) or newer, on arm64 and x86_64. The terminal library's Zig code uses ELF thread-local storage, which Android's loader only supports from Android 10.

What it does

Herdr concept In Bellterm
Host and session Nodes on the start screen, grouped and searchable, each with a colour label; tap one to attach. A node's group is typed, picked from the groups in use, or left blank in the node editor. Each node names a Herdr session (default unless you use named sessions).
Workspaces The navigation drawer (☰), with branch, ahead/behind, linked worktree, and the daemon's status dot. New workspace at the bottom. The drawer lists workspaces and agents; tabs are switched from the tab row.
Tabs The tab row under the top bar, with each tab's status dot; + opens a new tab, named as you type it or numbered by Herdr when left blank.
Panes Drawn as Herdr lays them out. Tap a pane to focus it; split, zoom, and close from the ⋮ menu.
Agents Listed in the drawer with Working / Needs input / Done / Idle; tap one to jump to its pane. When the app is in the background, the daemon's own "needs input" and "finished" notifications become Android notifications.

Reaching hosts

  • Jump hosts. A node can name another node as its jump host, which can have its own, as ssh -J a,b host does. Every hop's host key is checked and trusted separately; the trust prompt names the hop.
  • Herdr's saved machines. When Herdr on a host has saved SSH machines with herdr machine add, the session drawer lists them under Machines with the host itself, as Herdr's own sidebar does. Tapping one opens its session, reached through the host: the host's own ssh signs in to the machine with its keys, configuration, and known hosts, so the machine needs nothing new from the phone. Each machine is saved as a node shown via its host, removed along with the host. Running herdr --remote inside a pane instead shows the other server only as that pane's terminal, since Bellterm's workspaces are those of the server it attached to.
  • Keys and certificates. Keys & certificates (the lock icon) holds the device key generated on the phone, generated keys, and imported OpenSSH private keys (RSA, ECDSA, Ed25519; a passphrase is used once to decrypt). Private keys are stored encrypted with an AES-GCM key held by the Android Keystore. Attach an OpenSSH user certificate (*-cert.pub) to a key for hosts that trust a CA (TrustedUserCAKeys); Bellterm checks that it certifies the key and shows its principals and validity.
  • Passwords can be saved per node, in the node editor or with Remember password when asked, encrypted like private keys with the Android Keystore's AES-GCM key; a hop without a saved password is asked for one on each connection. Forget saved password in the node editor, switching the node to key sign-in, or deleting the node removes it. When a host rejects a saved password, the session offers Enter password for that hop, and the new password replaces the saved one. Hosts that ask through keyboard-interactive get the same password.
  • SSH config import. Paste or choose your ~/.ssh/config: every Host alias becomes a node, HostName/User/Port/ServerAliveInterval are applied with OpenSSH's first-value-wins rules (wildcard and negated Host patterns included), and ProxyJump chains become jump-host nodes. Match and Include are reported, not applied; keys named by IdentityFile are imported separately.
  • Known hosts lists trusted fingerprints by host:port; forgetting one re-prompts on the next connection. A changed key is refused with a warning.
  • Keepalive per node keeps mobile connections from idling out.

Appearance

  • Liquid glass in the style of ColorOS 16, built on coui-blur: frosted cards, capsule toolbars, and a progressively blurred top bar over flat colours, with bloom highlights on glass rims and refraction on primary buttons. Below Android 13, which lacks the shaders, the same surfaces are drawn as dense tints.
  • Bellterm's own brass-and-slate palette in light and dark; light/dark follows the system or is fixed.
  • English and Simplified Chinese. Settings > Language follows the system by default (any Chinese system locale gets Chinese) or pins one; on Android 13 and later the choice is the system's per-app language, also under the app's entry in system settings.
  • Terminal colour schemes for dark and light separately: Bellterm, Catppuccin Mocha/Latte, Dracula, GitHub Light, Gruvbox, Nord, One Dark, Solarized, Tokyo Night. The scheme also becomes the host theme Herdr reports to pane programs.
  • Fonts with Nerd Font icons. JetBrains Mono Nerd Font Mono ships in the app; Fira Code, Cascadia Code, Source Code Pro, and Ubuntu Mono download in-app from the nerd-fonts v3.5.1 release, each file checked against a pinned size and SHA-256. Any TTF/OTF can be imported, and the system monospace face is offered too; for fonts without Nerd Font icons, the bundled Symbols Nerd Font draws them.

Android conventions it follows:

  • Back closes the drawer, then returns to the node list without detaching. A foreground-service notification shows the attachment, with Disconnect.
  • The soft keyboard types straight into the focused pane: no suggestions or autocorrect, and CJK input methods compose in place at the cursor.
  • An extra-keys row sits above the keyboard: Esc, Tab, latching Shift, Ctrl and Alt for the next key (they combine, e.g. Shift+← or Ctrl+Shift+→), arrows and paging keys that repeat while held, and symbols phone keyboards hide.
  • Drag or fling to scroll a pane, pinch to change the font size, long-press to select text with the system Copy / Paste toolbar. The bell can vibrate, and the screen can stay on during a session.
  • Hardware keyboards work, including Ctrl and Alt chords.

Closing a pane, tab, or workspace asks first, because Herdr ends the programs in it.

Signing in

On first launch Bellterm generates an Ed25519 key on the device. Add its public key (Keys & certificates → Copy public key) to the host:

echo 'ssh-ed25519 AAAA… bellterm@Pixel7' >> ~/.ssh/authorized_keys

or sign it with your SSH CA and attach the certificate. The first connection to each hop shows the host key's SHA-256 fingerprint for you to compare with ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub on that host before trusting it.

The host that runs Herdr needs /bin/sh, or PowerShell on a Windows OpenSSH host, and Herdr 0.9.0 or later in one of the usual install locations (for example ~/.local/bin/herdr, or herdr.exe on PATH on Windows). When a connection finds Herdr missing or older than that, the session offers Install Herdr or Update Herdr: on your tap, Bellterm runs herdr update --handoff with the Herdr it found, which hands running sessions to the new version, or downloads Herdr's installer from https://herdr.dev/install.sh and runs it, which puts herdr in ~/.local/bin. The installer needs curl or wget on the host. A Windows host gets https://herdr.dev/install.ps1 through PowerShell instead. Nothing else is installed, and nothing is started or stopped: if no Herdr server is running for the session, start one there with herdr. Jump hosts need only SSH with TCP forwarding allowed.

How it works

flowchart LR
    subgraph phone["Bellterm"]
        ui["Kotlin + Compose<br/>hosts, drawer, tabs, gestures, IME"]
        core["bellterm (Rust, JNI)"]
        ghostty["libghostty-vt<br/>terminal state, graphemes, colours"]
        client["herdr-client + herdr-protocol"]
        ssh["russh<br/>in-process SSH"]
        ui <--> core
        core <--> ghostty
        core <--> client <--> ssh
    end
    ssh <-->|"SSH exec:<br/>herdr remote-client-bridge"| daemon["herdr daemon on the host"]
Loading
  • Transport. Android has no ssh executable, so the core uses russh on a thread of its own. It runs the same remote bridge discovery script a desktop client runs through ssh, and answers it with herdr_client::answer_remote_bridge; the channel is pumped through a Unix socket pair into herdr-client's ordinary worker.
  • Terminal. Herdr sends rendered cell grids, not a byte stream. Each surface is written into a libghostty-vt terminal as VT (changed rows only, with control characters stripped from cell symbols), and frames are read back from its render state: grapheme clusters, wide characters, colour resolution through the theme palette, and the cursor all come from Ghostty. The view draws those frames on a Canvas.
  • Threads. The Rust core owns every blocking operation. A screen thread owns libghostty (whose types are not Send) and publishes only the latest frame and shell view, so a slow view never queues stale frames. The Kotlin side pulls events on a background thread; the UI thread never blocks.
Path Responsibility
native/src/ssh/ Routes through jump hosts, host key pinning, key/certificate/password auth, bridge pump
native/src/config.rs The route document Kotlin sends, parsed into zeroizing types
native/src/keys.rs Key generation and import, certificate inspection
native/src/ssh_config.rs OpenSSH client configuration import
native/src/vt.rs Herdr cells (and popups) as VT for libghostty
native/src/screen.rs, render.rs libghostty terminal; frames packed for Kotlin
native/src/session.rs Connection, event mailboxes, input routing
native/src/input.rs Android key codes and touches as Herdr semantic input
native/src/jni_api.rs app.bellterm.core.Native
app/src/main/java/…/core JNI wrapper, frame and shell-view parsing, Connection
app/src/main/java/…/ui Compose screens and the TerminalView
crates/herdr-client, crates/herdr-protocol Herdr's wire protocol and client worker (Apache-2.0, see NOTICE)

Building

Requirements: JDK 17, the Android SDK (platform 35) and NDK 27.2.12479018, Rust with the aarch64-linux-android and x86_64-linux-android targets, cargo-ndk, and Zig 0.15.2, which libghostty-vt-sys uses to build Ghostty (the pinned Ghostty commit requires exactly that version).

rustup target add aarch64-linux-android x86_64-linux-android
cargo install cargo-ndk --locked
# local.properties (not committed):
#   sdk.dir=/path/to/Android/Sdk
#   zig.dir=/path/to/zig-0.15.2
just build      # app/build/outputs/apk/debug/app-debug.apk (Bellterm)
just test       # Rust core tests on the host, then Kotlin unit tests

End-to-end UI tests drive the debug build on a connected device through UiAutomator, screen by screen, and save screenshots under the app's external files (Android/data/app.bellterm/files/e2e/). They clean up what they create. To include a live connection, name a host whose authorized_keys trusts the device key (the host key's fingerprint is needed only if the device has not trusted it yet):

just e2e                                   # without a host
just e2e 10.0.0.5 22 me                    # host, port, user
just e2e 10.0.0.5 22 me SHA256:…           # and the expected host key

Gradle runs cargo-ndk before every build. If Zig cannot fetch Ghostty's dependencies (it uses its own resolver), prefetch them into the Zig cache with zig fetch <url> on each URL it reports.

The release build is minified. To sign it with your own key, point the build at a keystore through environment variables (or Gradle properties of the same names, such as in ~/.gradle/gradle.properties); without them it is signed with the debug key:

keytool -genkeypair -keystore bellterm-release.jks -alias bellterm \
  -keyalg RSA -keysize 4096 -validity 10000
export BELLTERM_KEYSTORE=/path/to/bellterm-release.jks
export BELLTERM_KEYSTORE_PASSWORD=…   # BELLTERM_KEY_PASSWORD too, if it differs
export BELLTERM_KEY_ALIAS=bellterm
./gradlew assembleRelease           # app/build/outputs/apk/release/app-release.apk

Keep the keystore and its passwords out of the repository: every later update must be signed with the same key, or Android refuses to install it over the existing app.

Publishing an update

The app checks https://dl.bellterm.app/latest.json at most once a day, and whenever Check for updates is tapped in Settings. When it lists a higher versionCode, the node list offers the release; Download opens its APK in the browser. To publish one:

  1. Optionally write release notes to release-notes/<version>.en.txt and .zh.txt on main, one line per change: they become the update banner, the GitHub release, and the app's What's new in Settings. Add the release to bellterm.app's changelog too, site/changelog/ and site/zh/changelog/.
  2. Run the Release workflow from the Actions tab with the version, such as 1.2.0. It sets versionName and versionCode (10200) in app/build.gradle.kts, builds the APK with the release key (from the BELLTERM_* repository secrets, the keystore base64-encoded as BELLTERM_KEYSTORE_BASE64), writes latest.json, pushes the version commit and the tag v<version>, and attaches both files to a GitHub release.
  3. The same run uploads bellterm-<version>.apk, bellterm.apk (the site's download link), and then latest.json to the R2 bucket behind https://dl.bellterm.app/ (secrets CLOUDFLARE_R2_TOKEN and CLOUDFLARE_ACCOUNT_ID), in that order, so the manifest never points at a missing file.

Pushing a tag v<versionName> after raising the version by hand runs the same build and upload.

To do it locally instead, build with the release key and run scripts/release-manifest.sh app/build/outputs/apk/release/app-release.apk dist.

Google Play

Every release also builds bellterm-<version>-play.aab with -Pbellterm.play=true, which leaves out the in-app update check that Play's policy forbids, and attaches it to the GitHub release. Bellterm is not on Play yet. These steps happen once, in Play Console, by the account owner:

  1. Create the app with package app.bellterm, free. Complete the store listing, the privacy policy (https://bellterm.app/privacy/), data safety, content rating, and target audience, and declare the specialUse foreground service: it keeps the SSH connection to the user's Herdr daemon open while agents run.
  2. Under App signing, upload the existing release key (Play's PEPK tool) rather than letting Google generate one, so a Play install and the APK from dl.bellterm.app can update each other. The same key is then the upload key.
  3. Upload the first bundle by hand to internal testing; Play's API accepts an app's uploads only after that.
  4. In Google Cloud, enable the Google Play Android Developer API, create a service account with a JSON key, and invite it in Play Console under Users and permissions with release rights for Bellterm. Store the key as the repository secret PLAY_SERVICE_ACCOUNT_JSON.

From then on the Release workflow uploads each bundle to the internal testing track, with the release notes in English and Chinese. Promote it to closed testing or production in Play Console. The script refuses an APK signed with the debug key.

Website

site/ is bellterm.app, served as static assets by the Worker in wrangler.jsonc. The Site workflow checks it on pull requests and deploys it on every push to main that touches site/ or wrangler.jsonc, with the secrets CLOUDFLARE_WORKERS_TOKEN (a token that can edit Workers and their custom domains) and CLOUDFLARE_ACCOUNT_ID. Run it from the Actions tab to redeploy main. Do not deploy from a local checkout.

Live test

native/tests/live_ssh.rs connects over real SSH to a real daemon: it checks the host key prompt, attaches, reads a frame back through libghostty, types a command, and sees its output. It types into the focused pane, so point it only at a throwaway daemon:

cd native
cargo run --example keygen -- /tmp/bellterm-key   # prints the public key
BELLTERM_LIVE_HOST=127.0.0.1 BELLTERM_LIVE_PORT=2222 \
BELLTERM_LIVE_USER=$USER BELLTERM_LIVE_KEY=/tmp/bellterm-key \
  cargo test --test live_ssh -- --ignored --nocapture attaches_over_ssh

Set BELLTERM_LIVE_PASSWORD instead of BELLTERM_LIVE_KEY to sign in with a password.

installs_herdr_then_attaches in the same file needs a host without Herdr: it waits for the install prompt, installs Herdr the way the app's Install Herdr button does, attaches, then runs the update path and attaches again. CI runs it against Windows OpenSSH on a windows-2025 runner, once with cmd.exe and once with PowerShell as the default shell. The test binary is built on Linux and runs in WSL there, which shares the runner's localhost.

attaches_to_a_saved_machine_through_its_host needs the host's Herdr to have saved a machine labelled BELLTERM_LIVE_MACHINE, whose session has a workspace labelled BELLTERM_LIVE_MACHINE_WORKSPACE: it lists the host's machines, attaches to that one through the host, and checks that an unreachable target reports the host's ssh error. CI runs it with the host and the machine as two Herdr sessions behind one local sshd.

Set BELLTERM_LIVE_JUMP_PORT to reach the target through a jump host on the same address, and BELLTERM_LIVE_CERT to a certificate for the key to sign in with it (point the target's TrustedUserCAKeys at the CA and its AuthorizedKeysFile at none to prove the certificate is what is used).

Limitations

  • Inline images (Kitty graphics, Sixel) are not drawn yet.
  • Generated keys are Ed25519; RSA and ECDSA keys can be imported but not generated. FIDO/security-key (sk-) keys and SSH agents are not supported.
  • Match and Include in imported SSH configuration are not evaluated.

License

Bellterm is released under the Apache License 2.0. The Herdr protocol and client crates in crates/ are third-party code under the same licence with their own copyright, and the bundled fonts keep their own licences; NOTICE lists each of them.

About

Bellterm: an Android client for Herdr daemons over SSH, with libghostty-vt as the terminal

Topics

Resources

Stars

8 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages