Bellterm is a native iOS 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 iOS 26 or newer, on iPhone and iPad, and is built for iPhone Duo. It shares its Rust core with Bellterm for Android.
Install: join the beta on TestFlight.
| Herdr concept | In Bellterm |
|---|---|
| Host and session | Nodes on the start screen, grouped and searchable, each with a colour label; tap one to attach. Each node names a Herdr session (default unless you use named sessions). |
| Workspaces | The sidebar, with branch, ahead/behind, linked worktree, and the daemon's status dot. New workspace at the bottom; long-press a workspace to rename or close it. |
| Tabs | The tab strip above the terminal, 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 session menu. |
| Agents | Listed in the sidebar with Working / Needs input / Done / Idle; tap one to jump to its pane. The daemon's "needs input" and "finished" notifications show as banners while the app is open. |
- Closed, the outer display shows one column, with the sidebar behind a button.
- Open, workspaces and agents sit beside the terminal. Toolbars move to the side as the system lays them out.
- Folded like a book, the sidebar takes the leading half, so the terminal and its controls stay clear of the fold.
- Folded like a laptop, the terminal fills the raised half and the keyboard with its extra keys the flat half.
Layout follows size classes and the fold's reserved region, never the hinge angle or the device model, so the same code serves iPhone, iPad, and Split View.
- Jump hosts. A node can name another node as its jump host, which can have
its own, as
ssh -J a,b hostdoes. 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 sidebar 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 ownsshsigns 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, and is removed along with the host. - Keys and certificates. Keys & certificates 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
Keychain items readable only on this device while it is unlocked. 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, in the Keychain like private keys; a hop without a saved password is asked for one on each connection. When a host rejects a saved password, the session offers Enter password for that hop.
- SSH config import. Paste or choose your
~/.ssh/config: everyHostalias becomes a node,HostName/User/Port/ServerAliveIntervalare applied with OpenSSH's first-value-wins rules, andProxyJumpchains become jump-host nodes.MatchandIncludeare reported, not applied; keys named byIdentityFileare 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.
- Liquid Glass throughout: the tab strip, extra keys, banners, and state card are glass, and the app icon is an Icon Composer icon with dark and tinted renditions. Light and dark follow the system or are fixed in Settings.
- English and Simplified Chinese, following the system; the app's language can also be set under its entry in the Settings app.
- 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, Source Code Pro, and Ubuntu Mono Nerd Font Mono ship in the app in every style, so nothing is downloaded. 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.
iOS conventions it follows:
- The 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 rides on the keyboard: Esc, Tab, latching Ctrl and Alt for the next key, arrows and paging keys that repeat while held, symbols phone keyboards hide, and a key that lowers the keyboard.
- Drag or fling to scroll a pane, pinch to change the font size, long-press to select text and copy or paste from the edit menu. The bell can tap a haptic, and the screen can stay on during a session.
- Hardware keyboards work, including Ctrl and Alt chords and repeating keys.
- iOS suspends apps in the background, so attachments close there and reopen on return; Herdr keeps everything running meanwhile.
Closing a pane, tab, or workspace asks first, because Herdr ends the programs in it.
On first launch Bellterm generates an Ed25519 key on the device. Add its public key (Keys & certificates → This device → Copy) to the host:
echo 'ssh-ed25519 AAAA… bellterm@iPhone' >> ~/.ssh/authorized_keysor 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 /opt/homebrew/bin/herdr, or herdr.exe on
PATH on Windows). Nothing is installed, started, or upgraded on the
host: if no Herdr server is running for the session, start one there with
herdr. Jump hosts need only SSH with TCP forwarding allowed.
flowchart LR
subgraph phone["Bellterm"]
ui["SwiftUI + UIKit<br/>nodes, sidebar, tabs, gestures, text input"]
ffi["bellterm-ffi (UniFFI)"]
core["bellterm (Rust)"]
ghostty["libghostty-vt<br/>terminal state, graphemes, colours"]
client["herdr-client + herdr-protocol"]
ssh["russh<br/>in-process SSH"]
ui <--> ffi <--> core
core <--> ghostty
core <--> client <--> ssh
end
ssh <-->|"SSH exec:<br/>herdr remote-client-bridge"| daemon["herdr daemon on the host"]
- Transport. iOS has no
sshexecutable, so the core uses russh on a thread of its own. It runs the same remote bridge discovery script a desktop client runs throughssh, and answers it withherdr_client::answer_remote_bridge. - Terminal. Herdr sends rendered cell grids, not a byte stream. Each surface is written into a libghostty-vt terminal as VT, 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. A UIKit view draws those frames with Core Text.
- Threads. The Rust core owns every blocking operation and publishes only the latest frame and shell view, so a slow view never queues stale frames. Swift pulls events on a thread of its own and applies them on the main actor, which 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 the app 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 the app |
native/src/session.rs |
Connection, event mailboxes, input routing |
native/src/input.rs |
Key codes and touches as Herdr semantic input |
ffi/src/lib.rs |
The Swift surface: free functions and the Session object |
app/Bellterm/Core |
Connection, frame and shell-view parsing, route documents, key mapping |
app/Bellterm/UI |
SwiftUI screens and the TerminalUIView |
crates/herdr-client, crates/herdr-protocol |
Herdr's wire protocol and client worker (Apache-2.0, see NOTICE) |
Requirements: Xcode 27.1 or newer, XcodeGen,
pkg-config, Rust with the aarch64-apple-ios and aarch64-apple-ios-sim
targets, and Zig 0.15.2, which libghostty-vt-sys uses to build Ghostty
(the pinned Ghostty commit requires exactly that version).
just test # Rust core tests on the host
just core # app/Generated: the core as an xcframework, and its Swift bindings
just project # gathers the bundled fonts, then app/Bellterm.xcodeproj
just test-app # Swift tests on an iPhone simulatorlibghostty-vt-sys has no iOS target, so scripts/build-core.sh builds
Ghostty natively with its xcframework enabled, takes the iOS device and
simulator archives from it, and points the crate's pkg-config feature at
them.
Zig 0.15.2 cannot link against the libSystem stubs of macOS SDK 26.5 and
later, and does not run on macOS 27 at all, so just core needs Xcode 26.0
selected on a macOS 26 host. CI builds the core that way and uploads it as the
bellterm-ios-core artifact; elsewhere, download it instead:
gh run download <run-id> -n bellterm-ios-core -D app/GeneratedTo run on a device, open app/Bellterm.xcodeproj and pick your team, or build
from the command line:
cd app
xcodebuild -scheme Bellterm -destination 'id=<device-udid>' \
DEVELOPMENT_TEAM=<team-id> -allowProvisioningUpdates
xcrun devicectl device install app --device <device-udid> \
~/Library/Developer/Xcode/DerivedData/Bellterm-*/Build/Products/Debug-iphoneos/Bellterm.apprelease-notes/<version>.en.txt and .zh.txt, one line per change, are
bundled into the app and shown in Settings → What's new, newest first,
with the installed version marked. Before a TestFlight build with a new
MARKETING_VERSION (app/project.yml), add its notes; a test fails when the
version being built has none.
- iOS suspends background apps, so attachments close while Bellterm is in the background and agent notifications arrive only while it is open.
- 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. MatchandIncludein imported SSH configuration are not evaluated.
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.