wooloo-mobile
The Android companion to wooloo, built with Kotlin + Jetpack Compose for herdr, the terminal
multiplexer for coding agents. wooloo mobile connects over SSH and uses herdr's own protocols to show your agents and
workspaces, let you reply to them, and drive any pane from your phone.
| Your spaces | Inside a space | Live pane | Connection states |
|---|
| | | |
Install and first connection
Requires Android 8 or newer and a reachable SSH account with herdr installed.
Google Play (closed test): follow the steps at wooloo.dev/mobile: join the
wooloo-mobile-testers group, opt in at
play.google.com/apps/testing/dev.wooloo.mobile with the same
Google account, and install it from Google Play. Google Play needs 12 testers for 14 days before the app can be public.
No server yet? Tap Try the demo machine on the first screen (also in Settings) to explore a simulated herdr
session with agents, terminals and alerts that runs on the phone.
APK: open latest release and choose its
wooloo-mobile-X.Y.Z.apk. If no release is available, distribution is not ready;
do not use a debug or smoke-test APK as a production release. Compare the published
SHA-256 and signer fingerprint, allow installation for your browser when Android asks,
and open the app. In-app updates need a separate installation permission for wooloo mobile.
See update and recovery instructions, including transition from debug installs.
Generate a phone key and authorize its public key as described below. Add a machine
manually or import its QR, verify the server fingerprint through a trusted channel,
select the authorized key, then Connect → space → agent → terminal. A QR does not grant
network access or authorize the key. Keep another working server login for recovery.
Privacy, license and support
Read the privacy policy, also available offline
in Settings. Quotas are experimental and require per-identity consent to read remote
agent tokens and query providers from the phone. Disabling them does not disable SSH.
The project code is MIT licensed; dependencies retain their own licenses (see the resolved inventory).
Original third-party notices are available offline in Settings → Third-party notices.
See the security and license review for dependency
updates, disclosure details and open distribution requirements, including provider
restrictions on the current Claude quota integration.
The launcher uses the readable name wooloo mobile. Provider names identify
interoperability and do not imply endorsement.
Report sanitized bugs through GitHub Issues.
Report vulnerabilities privately, as described in SECURITY.md. To contribute, read
CONTRIBUTING.md; the project follows the Contributor Covenant. The
release checklist tracks production signing, public availability and remaining validation.
How it talks to herdr
Everything runs over one SSH connection (sshj). Nothing needs to be installed on the server besides herdr, and
no ports are opened:
| Purpose | Remote command (exec channel) | Protocol |
|---|
| API calls (snapshot, create/rename/close, split, zoom, prompt…) | herdr --session <s> remote-api-bridge | herdr socket API: newline-delimited JSON, one request per connection |
| Live updates | same bridge, kept open with events.subscribe | lifecycle events + per-pane pane.agent_status_changed |
| Live terminal | herdr --session <s> terminal session control <pane> --cols C --rows R [--takeover] | NDJSON terminal.frame records (base64 ANSI) out; terminal.input / resize / scroll / mouse / release in |
| Watch-only | herdr terminal session observe <pane> | same frames, read-only |
The SSH connection is either a direct TCP port or a Cloudflare Tunnel (e.g. wooloo's Remote Access, or
cloudflared tunnel --url ssh://localhost:22). For a tunnel, wooloo mobile opens a WebSocket to wss://<hostname>/ and
carries the raw SSH stream in binary messages, exactly like cloudflared access ssh, so no cloudflared is needed
on the phone. Hostnames behind Cloudflare Access take a service token (CF-Access-Client-Id / -Secret).
remote-api-bridge is the stdio bridge herdr uses for its own saved SSH machines. As herdr's docs recommend,
events only invalidate state, and the authoritative view always comes from session.snapshot.
Non-interactive SSH sessions often lack ~/.local/bin on PATH, so the app looks for herdr in the usual install
locations, or uses the path you set per host.
API calls and subscription handshakes have a 20-second deadline, including exec-channel acquisition.
Cancellation interrupts channel IO; if it remains blocked after 250 ms, the app closes the SSH transport
so reconnect can recover it. Graceful channel cleanup runs on an IO thread with a separate 250 ms budget;
it can add that cleanup time to a request deadline. A peer that never acknowledges channel closure also
causes a transport reset. Cancelling an interruptible subscription normally preserves the shared transport.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
