Pair the Android app to review agent requests
The handup mobile app is a companion to the daemon on your computer, not a
daemon of its own. For a direct connection, set up
Tailscale on both devices, then run
handup remote tailscale on the computer. It is the recommended route; a
configured relay also works with remote access off.
Android is a beta, sideloaded APK published with each handup release
(handup-android_<version>_arm64.apk); there is no Play Store listing or
native iOS app. See downloads and releases for availability.
Phone clients never execute command requests and have no Run or Run as
admin button. Approval grants permission to the agent; it does not start a
desktop run. Paired devices cannot submit run_result. A command run locally
in the desktop app can still be reviewed in History with its returned result.
During a desktop run, the phone shows Running in the desktop app with the
elapsed time and the run limit, and decisions are blocked with 409 running in the desktop app. With a Can decide pairing, Stop asks the desktop to
stop the command (stop from another device);
agent cancellation also stops it. Expiry is paused while the claim lease (the
run limit plus 2 minutes) is active; if the desktop stops responding, the
request shows Run interrupted and can be decided again.
Install (Android)
Section titled “Install (Android)”Download the APK from the release on your phone, open it, and allow your browser to install unknown apps when Android asks, only if you trust the release. Verify it against the release checksums first if you can (see downloads). No Android SDK, Rust toolchain or application source is needed. The phone app then pairs with your computer.
For automatic updates, install Obtainium and
open this link
on the phone. Obtainium tracks the GitHub releases, installs only the
handup-android_ APK (not the Alpine Linux .apk packages in the same
release), skips prereleases, and notifies you when a new version is out.
Pairing
Section titled “Pairing”- On the computer, run
handup pair(add--scope viewfor a read-only device), or open Pair a phone in the desktop app. - In the app, tap Scan QR code and point the camera at the QR code. Or
paste the printed link (
http://100.x.y.z:7466/pair#code=…) into Pairing link and tap Pair with link. If the phone can’t run Tailscale, usehandup pair --relayinstead: the app then talks to the daemon through your end-to-end encrypted relay (…/pair#ch=…). - The code works once and expires after two minutes.
If remote access is off and Tailscale is connected, handup pair on a
terminal asks Turn on remote access over Tailscale now? [Y/n]. Enter or
y enables it and continues pairing. With --json, no terminal, or a
declined prompt, run handup remote tailscale first. Without Tailscale, set
it up or use a configured relay with handup pair --relay.
If handup pair reports that remote access is waiting for Tailscale, connect
Tailscale on the computer (sudo tailscale up on Linux, or open the Tailscale
app elsewhere), then retry pairing. With Tailscale mode enabled and no
remote.bind, the daemon keeps serving locally and binds the remote listener
automatically once Tailscale connects; no handup restart is needed. See
Remote troubleshooting.
If the phone cannot connect, run handup doctor on the computer. Its remote
row warns when Tailscale is missing/disconnected or nothing answers on the
tailnet port, and tells you how to fix it. handup remote off stops the remote
listener without unpairing your phone; a configured relay can still connect.
The app can pair with several computers (say a laptop, a desktop and a build server). Their pending requests share one inbox; once two or more are paired, each row and request shows a chip with its computer’s name. Approve, deny, previews, attachments, history and audit always go to the request’s own computer, and each computer stays the only authority for its requests (they never sync with each other). Pairing the same computer again replaces just that pairing.
Settings (the gear icon) lists the paired computers with the device name
and scope and the pinned certificate. Rename a computer there (the name
defaults to its hostname), tap Pair another computer to add one, or
Unpair one. Unpairing only forgets that computer’s token on the phone. To
cut the device off, also run handup devices revoke <id> on the computer.
When every paired computer has revoked the device, the app shows “This device
was revoked” and offers pairing again; a single revoked computer shows as
offline in the header while the others keep working.
If Android’s secure storage can’t be read when the app starts (it can fail on a cold start, for example when you open the app from a notification), the app retries a few times, then shows Couldn’t load your computers instead of the pair screen. Your pairing is still stored: tap Try again, or Pair again instead to replace it.
If a computer is asleep or off the tailnet, its name shows as offline in the header (with one computer: “Can’t reach handup”) and the app keeps retrying; the other computers’ requests stay usable. History shows one computer at a time, picked above the search box.
Approval feedback
Section titled “Approval feedback”For ordinary Approve/Deny requests, Deny is on the left and Approve is
on the right in the bottom action row, above the phone’s safe area. Questions
follow the same rule (Decline left, Submit right), as do custom
choices: the agent’s primary option takes the right edge and deny options the
left. Extras such as Raw JSON or Edit & approve sit in a row above;
the allow scopes (Allow for session, Allow in project, Always allow)
fold behind an Allow… toggle there so the footer stays short.
To mirror every decision row (primary on the left, Undo above it), set
decisions.primary_side: left in the laptop’s config, or choose Settings →
Decisions → Approve button side → Left for this phone only. The 48px
feedback slot is always reserved above the controls: showing Undo, replacing
the feedback, or clearing it never moves the decision buttons. Undo has a 44px
touch target and is separated from the decision row.
Swipe the approval card—including its title and preview—right to approve or
left to deny, like dealing a card. The card follows your finger, tilts, and
shows a stamp with the option it picks: Approve or Deny, Submit or
Decline on a question, OK or Dismiss on an info notice, or an
agent’s own labels such as Apply prod or Not now. A short drag (about a
fifth of the card) or a quick flick sends it off; let go earlier and it springs
back. There is no separate swipe strip. Cancelled, edge-started, and
multi-finger gestures do nothing. Turn Swipe cards off under
Settings → Decisions to use only the buttons. Swipe right always picks the
approve option, also when the buttons are mirrored to the left.
An info notice has an optional Reply to the agent box under its summary;
the text goes with OK or Dismiss (button or swipe), and an empty box
tells the agent nothing. With a hardware keyboard, Ctrl+Enter in the reply
box sends OK with your text; in Feedback for the agent, it sends
Approve with your feedback. Plain Enter inserts a newline.
Vertical scrolling and pinch zoom remain native. A drag locks to an axis after
a few pixels: mostly-vertical drags scroll, mostly-horizontal drags move the
card from anywhere on it, including file lists, diffs and code previews. A
preview that is already scrolled sideways (a long code or diff line) scrolls
back to its edge first; the next drag moves the card. Taps on buttons, file
rows and checkboxes still work. Swipes starting on input fields, sliders,
media controls or an existing text selection do not decide. Interactive HTML
frames keep their own input. Buttons and tabs have 44px touch targets on
narrow screens.
On a question, a right swipe picks the only choice of any unanswered
single-choice question (such as a lone OK) and submits; if a question is
still unanswered, the card springs back and shows Pick an answer. A request
with no deny option springs back on a left swipe. The buttons remain available;
swipes are not offered for requests with several approve options or several
deny options, multiple selected requests, or view-only devices. Both methods use
the same validation, biometric gate, and held-send/Undo behavior.
After the last decision, All clear replaces the card, but Undo remains in
the same bottom slot above the former Approve button—not in the center of the
screen. The last action row’s space remains reserved during the Undo window.
Long titles truncate so the countdown and Undo stay visible. Swipe through
several requests quickly and every decision still waiting keeps its own
countdown and 44px Undo: the newest stays in the footer slot, older ones
stack above it over the card (up to four, then “+N more”), so you can take
back any one without the buttons moving. Desktop keeps its compact sizing and
shows the U shortcut.
While the app stays visible, decisions wait for the undo window (5 seconds by default). Switching apps or otherwise hiding handup ends that window and hands held decisions to delivery immediately. On Android, a native outbox keeps retrying offline decisions in the background; see Offline for limits.
Inbox filters
Section titled “Inbox filters”The Android app uses the same filters as desktop. One sideways-scrolling row shows request-type chips with counts for types present in the inbox (and any selected types). Pick several to show any of them; tap again to remove a pick. No All chip is needed: nothing picked shows everything.
The Filters button opens a bottom sheet with Type and Agent sections. Picks within a section combine with OR; across sections they combine with AND. Agent picks appear after a divider as removable chips, with their count on the Filters button. The reset icon at the row end appears while filters or an Inbox query are active and clears both.
Tap the search icon in the Inbox filter row to open a focused search field
(or press / on a hardware keyboard). Search is hidden by default, with no
setting. A case-insensitive substring matches title, summary, folder (cwd),
repo, branch, agent, or session title, combined with your chip/sheet filters
(AND). An empty result shows No matches. × or Esc in the field clears
and closes search; reset also clears the filters. Auto-handled has no search.
Unread automatic decisions appear above the list as N auto-handled · View,
not as a tab. Tap View for the read-only Auto-handled view, ← Inbox
to go back, or Mark read to leave those decisions in History. Marking read
syncs to every device connected to that computer’s daemon and survives daemon
restarts; each paired computer has its own read state. Updating shared read
state needs decide access; view-only devices follow it.
Select and delete
Section titled “Select and delete”With Can decide access, tap a row’s ⋮ button in Inbox or History, or long-press the row, to open its menu. Delete asks to delete just that row; Select enters multi-select with that row checked. There is no Select button beside Inbox/History. In select mode, tap rows to toggle them; Select all picks the currently shown matches, Clear unchecks them, and Done exits. Choose Delete, review the inline warning, then Delete N to confirm or Keep to go back without deleting. The bar stays above the safe area and shows results/errors inline. In Inbox, approval buttons and decision swipes are paused while selecting.
With a mouse, right-click also opens the row menu. On a hardware keyboard, x
picks or unpicks the cursor row, entering select mode if needed; Delete or
Backspace asks to delete the picked rows, or the cursor row when none are picked.
Deletion acts on each request’s own computer: it cancels pending requests first, then permanently removes the requests, audit rows and preview files no remaining request uses. Waiting agents receive cancelled, never approval. There is no Undo, and view-only pairings cannot delete. See select and delete.
File bundles, multi-file diffs and requests with several previews have
Previous/Next buttons and an n of N counter, wrapping at either end.
On a hardware keyboard, [ / ] cycle files in the current preview (or
previews if it has no multiple files), and { / } always cycle previews.
They work in Inbox and History and leave typed brackets alone in input fields.
History
Section titled “History”The Inbox | History switch above the request list shows resolved requests grouped by day, with search and a single sideways-scrolling row of outcome chips with colored dots. Select several outcomes to show any of them; nothing selected shows every outcome.
Filters opens a bottom sheet with Outcome, Type, Agent, and Has files sections. Picks within a section combine with OR; across sections they combine with AND. Type, agent and Files picks appear after a divider as removable chips, with their count on the Filters button. The reset icon clears chip/sheet filters but keeps your search.
Tap a request for the read-only detail with the decision summary and audit trail; History (or the back gesture) returns to the list. It uses the same history API as the desktop app, so a view-only device sees it too. Use a row’s ⋮ menu to Delete it after confirmation, or Select it for multi-select. When older pages remain, Select all loaded means only loaded matches, not all history on the computer. The decision detail stays read-only; deletion still needs Can decide.
Security model
Section titled “Security model”- The token stays out of the webview. The React UI calls Rust commands.
Rust attaches
Authorization: Bearer <device token>and talks to the daemon over its own HTTP/WebSocket client. No command returns the token. - Secure storage. On Android the pairing (base URL, fingerprint, token) and
settings are sealed with AES-256-GCM under a non-exportable Android Keystore
key (
SecureStorePlugin, aliashandup-secure-store). Only the ciphertext is written to the app-privateshared_prefs/handup.secure.xml. App backup is disabled (allowBackup="false"). On iOS the Keychain would be used through thekeyringcrate. - TLS pinning. When the pairing link carries a certificate fingerprint
(
fp=, e.g.directmode with its self-signed certificate), the app accepts only a server certificate whose SHA-256 matches it. Without a fingerprint, HTTPS URLs are checked against the public web roots. Intailscalemode the daemon listens on plain HTTP inside the tailnet, and WireGuard provides the encryption. - Relay pairing. A relay link carries the daemon’s Noise static public key
(
pk=) and the device’s relay bearer credential (dk=). The app pins the key and runsNoise_IK_25519_ChaChaPoly_SHA256with the daemon, so the relay sees only ciphertext. The app’s per-device Noise key and the channel credential live in the same Keystore-sealed pairing.
Biometric confirmation
Section titled “Biometric confirmation”Approving a high-risk request asks for your fingerprint or face, or falls back to the screen lock PIN or pattern (“Use PIN”). Denying never asks, and neither do low- or medium-risk requests. The setting Confirm high-risk approvals is on by default. Turning it off requires the same confirmation when the device has a lock screen. The gate fails closed. If the device has no screen lock, high-risk approvals fail with an error until you set one up or turn the setting off.
Turning on Hard YOLO from the header switch (YOLO mode) asks for the same confirmation, since it auto-approves high-risk requests.
Rust enforces this gate on the same URI path the daemon routes, even when an API call includes query parameters. Fragments and malformed request targets are rejected before forwarding.
The prompt appears when you tap Approve or swipe to approve, before the few-second undo window and before an offline approval is queued. The confirmation covers that request at that content only: if the request changes before the approval is sent, the daemon refuses it. On Android, a queued high-risk approval with its tap-time confirmation can send in the background. Without that confirmation, it waits for the open app and prompts there; background delivery never bypasses the gate.
Offline
Section titled “Offline”The header pill shows whether the phone is in sync with your computer: Live (changes arrive as they happen), Syncing… (catching up or reconnecting; you can keep browsing and deciding), or Offline · synced 14:03 (the time of the last sync). Every state shows a sync icon (green on Live, spinning while syncing and briefly after a tap); tap the pill to sync now. The app also resyncs the moment it returns to the foreground, the network comes back, its event stream reconnects, or a push notification arrives, and while it is on screen it quietly refetches the queue on the Settings → Sync timer (default every 15 seconds). In the background it does not poll: configured push notifications can wake it, and opening the app resyncs. The licensed gateway is live for license holders using verified official-app phones. The daemon pings the event stream every 25 seconds (through a relay, the relay’s own pings every 30 seconds count); a stream that stays silent for 75 seconds (a network change, or Android dozing) is dropped and reconnected rather than left looking live. Waking the phone after it slept reconnects any stream not heard from in the last 35 seconds.
Below the header, the app shows the same config notices as the desktop app when the computer’s config file is saved: Config reloaded, Restart daemon to apply: …, or config.yaml invalid (line N), kept previous (see live reload).
A request answered somewhere else (the laptop, the terminal, another phone) leaves the phone’s inbox as soon as the event arrives. If it is the one open on screen, it stays for a moment with its controls dimmed and the footer saying how it ended, e.g. Approved on laptop or Denied on another device, then moves to the next pending request, or All clear. It is in History as usual. In Split layout, if you are back on the phone’s list screen when the request you last opened is resolved elsewhere, the list moves on immediately and shows All clear after the last pending request.
Once the inbox has loaded, losing the connection to your computer never hides it. The last queue is kept on the phone, so opening the app while offline still shows it, marked with when it last synced.
Approve, deny, and answers made while offline are queued in Decisions waiting
to send, each marked Sending when connected with an Undo button. When
the connection returns they are sent in the order you made them, bound to the
content you saw. The first decision to reach your computer wins. If one from the
phone loses (the request was already answered elsewhere, expired, or changed
since), it is dropped, never retried and never counted as a second decision,
and its row says what happened, e.g. Already handled on laptop · Approved.
The same line appears in the footer when a decision sent while online loses
that race. Nothing is ever sent that you did not tap. Each computer keeps its
own cached queue and outbox: one being offline never holds back decisions for
another.
On Android, queued decisions are also stored in a durable native outbox
(outbox.db), separate from the disposable History/file cache. Rust delivers
them without relying on the webview to keep running. Hiding the app ends any
remaining undo windows and tries every queued decision, even for a computer
whose connection looked down. Network failures stay queued and retry in the
background.
When you leave the app with pending work, Android starts a foreground service.
Its silent Sending 1 decision… or Sending N decisions… notification
shows how many decisions are waiting and disappears when none are waiting.
If Android refuses to start the service, delivery waits for the next open.
Swiping handup away or Force stop stops background decision delivery until
you reopen it; queued decisions survive. Android 15 limits dataSync foreground
services to about six hours per day. When that allowance runs out, unsent
decisions remain queued for the next open. This native background delivery is
Android-only; desktop and web behavior is unchanged.
Unpairing a computer forgets its cached queue and any unsent decisions for it.
Offline copy and Downloads autosave
Section titled “Offline copy and Downloads autosave”The app keeps a copy of the History pages, request details, audit trails and files you read or that auto-download fetched, per paired computer, in an app-private SQLite database. Each time the app reconnects to a computer it also refreshes the newest History page (the 50 latest), so History opens offline even if you never looked at it. When that computer is unreachable, History serves the copy and shows Offline copy from … with its age; online, every read goes to the computer and refreshes the copy. Each page is one snapshot replaced on every refresh, never merged, so the copy cannot drift from or duplicate the computer’s history. Only these reads are kept: never the pending queue (it has its own store above), decisions or other writes, settings, pairing, devices, or any token. Files are checked against their SHA-256 before they are kept.
Each computer’s card in Settings has its own controls:
- History kept on this phone: Last 30 days (default) of the offline copy, Everything read, or Off (nothing is kept, files included).
- Space limit: 256 MB by default (16–4096). Past it, the least recently used entries go first; lowering it trims at once.
- Also save files to Downloads (off by default, Android 10 and later): new
requests’ named files, and files you open, are copied to
Download/handuponce each, up to a per-file limit (25 MB by default). It uses Android’s MediaStore, so no storage permission is asked. Saved files stay after you unpair; delete them in a file manager. - Clear cache deletes that computer’s copy only. Unpairing a computer also deletes its copy and settings; other computers keep theirs.
The copy holds request content (titles, previews, files), so anyone who can unlock the phone and open the app can read it offline. Set History to Off on a computer whose requests should not stay on the phone.
Storage
Section titled “Storage”Settings → Storage (shown once a computer is paired) keeps two kinds of
space apart, and never adds them together. The group summary shows both, for
example 80 MB on phone · 162 MB on Laptop.
On this phone comes first: the size of this phone’s
offline copy, one row per computer.
Clear asks for an inline confirmation (Clear this phone only: 80 MB. History on Laptop stays …), then deletes the copy on the phone only. Your
history on the computer is not deleted; it downloads again when needed.
On computer (for example On Laptop) follows for each paired computer: that computer’s own disk
use (a stacked bar and legend: request history, files and previews, audit log,
free database space, database log and other), pending/resolved/file counts and
the retention in force. With a Can decide pairing the phone has the same
controls as the desktop app: Keep request history,
Keep files and previews and Clean up computer now. The confirmation
says where data is deleted, for example Delete on Laptop and this phone: 120 requests …: a cleanup on the computer also clears this phone’s offline copy of
that computer. A View only pairing shows usage and how to clean up on the
computer (Settings › Storage in its desktop app, or
handup storage clean history --older-than 30d). It needs a daemon with
storage support; an older one shows an “update it” message.
Auto-download media
Section titled “Auto-download media”Settings → Previews decides whether the files of new pending requests (images, video, audio, PDFs and other files) download in the background, so their previews open at once instead of loading while you wait:
- Auto-download media: Always, Wi-Fi only (default; any network Android reports as unmetered counts), or Never (files load when you open them).
- Per request up to (MB): 50 MB by default (1–1024). A request’s files download in order while they fit; a file that does not fit is skipped and loads when you open it.
Downloads start when a request arrives, and again whenever the app reconnects to a computer (opening the app, network back, or a push notification waking it), so requests that arrived meanwhile are caught up. The setting applies to every paired computer and uses that computer’s offline copy: with History kept on this phone set to Off, nothing downloads. Opening a preview while its file is still downloading waits for that download instead of starting another.
Files also download when the app is closed. A push notification (or a relay wake-up) for a new request starts a short background download, so a large video is already on the phone when you tap the notification. It follows the same settings: Wi-Fi only by default, nothing under Never or with History kept on this phone set to Off, and no more than Per request up to (MB) per request. Swiping handup away is fine; Android’s Force stop blocks push until you open the app again. On Android 11 and older a silent Downloading attachments notification shows while it runs.
Play while downloading
Section titled “Play while downloading”Videos and audio start playing from the first bytes instead of after the whole
file has arrived, and you can seek ahead. A video shows a still poster frame
(made by the computer’s daemon, which needs ffmpeg; see
the daemon API) before you press play. While you watch, the
rest of the file keeps downloading, and once it is complete and checked it is
kept in the offline copy like any other file. Over mobile data the app does not
download beyond what you are watching unless you chose Always auto-download
and Always allow below. Turn Play while downloading off in
Settings → Previews to wait for the whole file instead; the phone then loads
the clip only when you tap Play.
Large files on mobile data
Section titled “Large files on mobile data”Before Play, Open or Download fetches a file of Ask above (MB) (10 MB by default, 1–1024) or more that is not on the phone yet, over a metered connection such as mobile data, the app asks once, inline under the file: This video (48 MB) will use mobile data. Choose Play / Open / Download to go ahead this time or Always allow to stop asking; Open and Download also have Cancel, and for Play you simply do not tap it. A Download of several files adds their sizes together. Files already in the offline copy never ask, and neither does Wi-Fi or another unmetered network.
In Settings → Previews, Large files on mobile data is Ask first (default) or Always allow, and Ask above (MB) sets the size for Ask first. Always allow does not turn on background downloads: those still follow Auto-download media.
Once a request is decided, expires or is cancelled, its downloaded files are deleted unless you opened them (opened files stay like any file you read) or another pending request still uses them. The computer’s Space limit caps everything kept, oldest-used first.
A download gives up only after 30 seconds without receiving anything, not after a fixed total time, so large files finish on a slow or relayed connection.
Display and navigation
Section titled “Display and navigation”Settings opens a full-screen page on Android, with a persistent Back button and independently scrolling sections. Android Back also returns to the inbox. Changes save automatically on this device; there is no separate Save step and no confirmation when you leave. The header always shows the save state: Saving…, Saved with a check, or Not saved with Retry. Back during a pending save waits for it to finish, then returns. If a save failed, Back keeps Settings open and offers Retry or Discard and go back; discarding keeps the settings that were actually stored.
Settings has collapsible Appearance, Decisions, Sync, Previews, Read
aloud, Dictation, Storage, License (one row per paired computer), Test, Keyboard shortcuts,
Help & feedback, and About groups alongside the paired-computer controls.
About lists the app version, commit, build date and platform, with Copy
for a bug report; the daemon’s version is shown in Settings › About on the computer.
Decisions contains the undo window, approve button side, and Swipe
cards; Sync holds Resync while open (Off, 10s, 15s, 30s, 1m, 5m;
default 15s), how often the open app re-checks each reachable computer, saved
per device; Previews holds auto-download media,
play while downloading and
large files on mobile data.
Keyboard shortcuts lists the gestures (swipe right or left to decide,
Undo, tap a row, back, drag the divider) and the keys a hardware keyboard
can use; when every paired computer is view-only it hides the deciding ones.
The list is read-only on touch/coarse-pointer devices; it shows the connected
computer’s configured keys. Change them from that computer’s desktop app or a
fine-pointer browser with decide scope, or use its
keys: config. Changes made in
Settings apply live across connected clients; gestures are unchanged.
Settings → Appearance sets the theme (System follows the phone’s light/dark
setting live, or Light, or Dark), color palette, density, and layout. The mobile
header has no separate theme shortcut. Density opens its own page with a live preview of each
choice; Back returns to Settings. Compact (the default) puts expiry, agent,
and location in small tabs on top of the preview; tap a tab to show that
detail. Comfortable shows them in a roomy header; Ultra-compact also
trims list rows and headers. In every density the risk badge sits in the
request header, next to the title.
Settings → Appearance → Layout opens a page with a preview of each choice: Split (default) shows the list, then the request you open; Stacked keeps the list above the request; Focus shows one request at a time; Rail adds a horizontal chip strip. Focus and Rail have ‹ › controls, N of M, and a Queue button that opens the full list in a sheet. Density applies inside every layout. Layout and pane sizes save on this device.
Drag the Split or Stacked divider to resize with touch or a mouse. With the divider focused, arrow keys adjust it; double-tap, double-click, or Enter resets it. Reset sizes also appears on the Layout page after resizing. Split width is 240–640px (default 380px); Stacked height is 15–75% (default 38%).
A paired computer flooded by one agent session (40 requests in a minute by default) shows a banner at the top of the inbox list, naming the computer when several are paired, with Mute 1h and Dismiss all (N pending); view-only pairings see the banner without the buttons. See floods and mutes.
Android Back closes an open dialog or settings, returns from a request (including one opened from a notification) to the list, and leaves the app only from the list. Command and text previews have a Copy button. Fenced code blocks in Markdown previews, summaries and questions have a Copy code button in their top-right corner (shown on hover or focus with a mouse, always on touch).
Settings → Test has one row per paired computer, each with Send test
request and Send test question. Choose the row for the computer whose
inbox and notifications you want to try. It creates a harmless server-built
sample on that computer, not on the phone: Test request or Test question,
low risk, agent handup, session handup-test, with a 15-minute timeout.
Approving, denying, or answering performs no action. The pairing needs
decide scope; a view-only computer returns an explanatory error. If the
computer runs an older daemon without this route, update it.
Read aloud
Section titled “Read aloud”Tap the speaker button (Read aloud) in an open pending request’s header; tap Stop reading to stop. It reads the agent, title, a shortened summary, risk, questions and, by default, numbered options—not previews, diffs or tool input. Changing or deciding the request, returning to the list, or opening History stops playback. History has no read-aloud button.
Settings → Read aloud saves the voice, Speed, Pitch, Read options and scope on this phone; Test voice plays a sample. This request is the default; Whole queue continues through the visible pending requests after the open one, selecting each in turn. Read new requests is off by default; when enabled, it can read a newly arrived request while handup is open and idle, but does not read the requests already waiting at first load.
The searchable voice picker filters by name, language name or code, and Natural or Online labels.
Android uses native TTS through tauri-plugin-tts, not the System WebView’s
speech APIs. By default it reads aloud with the system default text-to-speech
engine. To change the engine or install voices (for example if none appear),
use Android’s own text-to-speech settings, then reopen Read aloud in handup.
Online voices send the spoken text to the voice provider.
Voice provider chooses who speaks: This device (default, free) or a cloud voice from OpenAI or ElevenLabs. A cloud provider needs your own API key (see cloud speech providers); pick an OpenAI voice or paste an ElevenLabs voice ID, and optionally a Voice model (empty uses the provider’s default). The voice list and Pitch apply to This device only; Speed applies to both. For a phone browser rather than the native app, see Web UI read aloud.
Dictation
Section titled “Dictation”Tap the mic (Dictate) beside a text field, speak, then tap it again (Stop dictation). The words are added to the end of the field and stay editable; nothing is sent until you submit. The mic appears beside the free-text answer to a question, Feedback for the agent and Reply to the agent, text fields an agent asks you to fill in, and an email draft’s Subject and Body (not the raw JSON editor). While listening it shows what it has heard so far, and the Android recognizer also stops by itself when you stop speaking. Starting dictation stops read aloud first.
The first time, Android asks for microphone permission (RECORD_AUDIO). If you
deny it, the mic shows Microphone not available; allow it in Android’s app
settings and try again.
Settings → Dictation saves, on this phone:
- Provider: This device (default, free) uses Android’s own speech recognizer. Settings says which kind your phone has: On-device recognizes speech on the phone, offline (Android 12+ phones that support it); otherwise it Uses Google speech service, which may send your audio to Google. Or choose OpenAI, Groq or ElevenLabs, which record up to two minutes and send the recording to that provider; set an optional Transcription model (empty uses the provider’s default) and your API key.
- Language: Detect automatically (default) or a fixed language.
Cloud speech providers
Section titled “Cloud speech providers”Cloud dictation and cloud read aloud are optional and off by default. Paste your own API key into OpenAI API key, Groq API key or ElevenLabs API key and tap Save; the field then shows Configured, and Clear removes the key. A key saved under Read aloud also counts for Dictation and the other way round. Keys are encrypted with the Android Keystore on this phone, write-only (never shown again) and never sent to your computer, its daemon or a relay: the app calls the provider directly. Cloud providers receive your recorded audio (dictation) or the text being read (read aloud), and may bill your account for it.
Attachments and Markdown
Section titled “Attachments and Markdown”File attachments offer Download and Open on Android. Download fetches the attachment through your authenticated pairing, then opens Android’s save picker. Choose a location on the phone; the suggested name preserves the original basename, including Unicode. You may rename it, and the selected storage provider may adjust duplicate names. Cancelling saves nothing and shows Download cancelled. Wait for Saved followed by the final file name before assuming a download finished. A write failure reports an error and attempts to remove the newly created partial document; providers that refuse deletion may retain that partial file.
Open passes a temporary, read-only content URI and the file’s MIME type to an installed viewer. Another app receives the attachment, not your pairing token or the computer’s file URL. If no suitable viewer is installed, use Download and choose a compatible app. The private Open copy remains available until Android evicts the cache. Open hands over the file’s own type first, then plain text for text-like files (code, JSON, YAML…), then any app that accepts the file.
Files previews list every file with its size and type. Tap a row to view it
(code is highlighted, Markdown renders, images and media play), or use its
open icon to hand it to another app. Each viewed file has Open and
Download. Check rows (or the select-all box) to Download several at
once; more than one file downloads as a single .zip that keeps the folder
layout. On Android the .zip goes through the same save picker; the desktop
app asks where to save, starting in your Downloads folder.
HTML files only open in the sandboxed preview; download them instead.
Image previews keep Fit, −, the percentage and + visible over the bottom-right of the image in narrow panes; no hover is needed. Fit fits the image to the pane, − / + zoom out or in, and tapping the percentage returns to the selected scale (100% initially). Open and Download stay in the file row above the image, with no duplicate action row for an image inside a file bundle. Wider panes put the size controls in that same file row.
JSON previews are pretty-printed and syntax-highlighted with the active palette; switch to Tree to fold objects and arrays.
.md and .markdown attachments (case-insensitive), or attachments marked
text/markdown, render in the app with headings, lists, GFM tables and
syntax-highlighted fenced code. Unknown code languages remain readable plain
text. Tables and long code lines scroll inside the reader rather than widening
the page. Raw HTML is not rendered and remote images are blocked. Tapping a
web or mailto: link in Markdown, a summary or a plain-text preview opens it
in your browser or mail app, never inside handup; other links do nothing.
Open and Download remain available if reading fails.
These native file actions support Android; iOS attachment delivery is not implemented. Browser downloads continue to use the browser’s own file handling.
Notifications
Section titled “Notifications”Android can receive native Firebase Cloud Messaging (FCM) notifications directly
in handup; the ntfy app is not required. The licensed push gateway is live at
https://push.gethandup.dev for license holders using the official Android app.
Only phones with a proof-of-possession device ticket get woken. Self-hosted FCM
requires a sender in the APK’s Firebase project. Builds without Firebase
configuration receive no push.
Queued decision delivery uses a separate silent Sending decisions channel
(outbox, low importance), not FCM or ntfy. It has no sound, vibration, or badge
and is shown only while the foreground service has work waiting. This does not
require a Firebase-enabled build. Tapping it opens handup.
Android permissions
Section titled “Android permissions”The app declares FOREGROUND_SERVICE and FOREGROUND_SERVICE_DATA_SYNC to keep
queued decision delivery running after you leave it. These are manifest
permissions, not extra runtime prompts. Android 13+’s notification permission
controls notification visibility; it is requested after pairing as described
below. The service is still subject to Android’s start restrictions and
Android 15’s daily dataSync limit; reopening the app resumes queued work.
RECORD_AUDIO is requested only when you first tap the mic for
dictation.
Official app: licensed push gateway
Section titled “Official app: licensed push gateway”Install the official APK, install a signed license on the computer,
and pair the phone (Tailscale, direct, or relay). The default daemon backends
are [desktop, push]; existing
explicit lists must include push to use it. A trial alone is not enough, and
you do not need your own Firebase project or service-account credentials.
Android 13+ asks for notification permission after pairing.
The app proves possession of its FCM token automatically: it requests a challenge
from the gateway, receives a silent verify push, and exchanges its nonce for a
device ticket. Verification shows no notification. Rust stores the token and
ticket in Android Keystore-sealed storage and registers both with every paired
computer. A failed verification retries on app startup or token refresh; open
the app if handup doctor reports an unverified phone. Token-only registration
still works for self-hosted FCM; the licensed gateway wakes only verified phones.
notifications: backends: [desktop, push] push: url: https://push.gethandup.dev payload: wakenotifications.push.url requires HTTPS (loopback HTTP is allowed for local
tests). notifications.push.payload accepts wake (default, no title) or
title (redacted request title); neither sends preview content. The gateway
sees the signed license, phone tokens, device tickets, and request metadata (type, id, risk);
Google receives the tokens and notification data. Choosing title also shares
the redacted title with both. See notification backends.
handup doctor adds three rows. They report OK or WARN, never FAIL, and each
network check gives up after 3 seconds:
pushnames the route that sends phone notifications. It saysoffwhen notifications are off or no usable push backend is listed. Withfcmlisted it saysself-hosted FCM; N registered devices:fcmtakes precedence and this is not a fallback to the gateway. Otherwise it sayslicensed gateway <url>, whether a license is installed, how many phones are verified and unverified, and whether the gateway answered. It warns when there is no license, a phone is unverified (open the app on the phone to verify), no phone is paired, or the gateway is unreachable.push-lastshows the last delivery on that route and how long ago it was, for exampleok 2m ago to 2 devicesorrefused 5m ago: rate limited. The result isok,partial(some phones got it, or unregistered tokens were removed),refused(the gateway turned it down: rate limit, license, unverified phones, payload too large) orfailed(unreachable, gateway error, delivery failed). Anything butokwarns. Before the first push it saysno notifications sent yet. The daemon keeps only this summary (result, a fixed reason, device count, time), never tokens or provider error text.relaysaysoffwithoutremote.relay.url; otherwise it checks that the relay’s/v1/healthanswers and shows its protocol and version, or warnsrelay unreachable.
Self-hosted Firebase: owner setup
Section titled “Self-hosted Firebase: owner setup”The following build-time setup is for APK maintainers using their own Firebase project, not customer installation of the official APK. A service account from another project cannot send to the official app. For that app, use the live licensed gateway.
- In the Firebase console, create a
project and add an Android app with package name
dev.handup.app. - Download its
google-services.jsonand place it atapps/handup-app/gen/android/app/google-services.jsonbefore building the APK. This file is gitignored. The Google Services Gradle plugin is applied only when the file exists. Without it the release APK still builds, and Settings → Notifications says Not available in this build. - Enable the Firebase Cloud Messaging HTTP v1 API for the project. In
Project settings → Service accounts, generate a service-account private
key (or create a dedicated account with the Firebase Cloud Messaging API
Admin role). Save the JSON key on the daemon host, outside the repository,
readable only by its owner (
chmod 600). Never put this private key in the APK or commit it.
Steps 1–3 can be scripted with gcloud (logged in as the project owner). The
one manual step is opening the Firebase console once to add Firebase to the new
project, which accepts the Firebase terms; the API returns 403 until then.
P=handup-push-$(head -c3 /dev/urandom | od -An -tx1 | tr -d ' \n')gcloud projects create "$P" --name="handup push"gcloud services enable firebase.googleapis.com fcm.googleapis.com iam.googleapis.com --project "$P"# Console: Add project → choose the existing Google Cloud project "$P".T=$(gcloud auth print-access-token)H=(-H "Authorization: Bearer $T" -H "x-goog-user-project: $P" -H 'Content-Type: application/json')F=https://firebase.googleapis.com/v1beta1/projects/$Pcurl -s -X POST "${H[@]}" "$F/androidApps" -d '{"packageName":"dev.handup.app","displayName":"handup"}'APP=$(curl -s "${H[@]}" "$F/androidApps" | jq -r '.apps[] | select(.packageName=="dev.handup.app") | .appId')curl -s "${H[@]}" "$F/androidApps/$APP/config" | jq -r .configFileContents | base64 -d \ > apps/handup-app/gen/android/app/google-services.jsonSA=handup-fcm@$P.iam.gserviceaccount.comgcloud iam service-accounts create handup-fcm --project "$P"gcloud projects add-iam-policy-binding "$P" --member "serviceAccount:$SA" \ --role roles/firebasecloudmessaging.admin --condition None(umask 077; gcloud iam service-accounts keys create ~/.config/handup/firebase-service-account.json --iam-account "$SA")For CI-built APKs, store google-services.json as a protected GitLab CI file
variable named GOOGLE_SERVICES_JSON; the android job copies it into place.
-
Configure the daemon (saves apply live):
notifications:backends: [desktop, fcm]fcm:service_account: /absolute/path/to/firebase-service-account.jsonpayload: titlehandup doctorchecks the account and reports the project id without printing credentials. The APK and service account must use the same Firebase project. -
Install the configured APK and pair it with the daemon. Android 13+ asks for notification permission after pairing succeeds, not on initial launch. Settings → Notifications shows On or Blocked and opens the system’s app-notification settings. If the status cannot be read within a few seconds, it says Could not check with the reason and a Retry button. Android 12 and earlier use the system setting without a runtime permission prompt.
After pairing, the app registers its FCM token for each paired computer using
device authentication, whether or not notification permission is granted.
Every pairing registers at the daemon (PUT /v1/devices/self/push with
{"platform":"fcm","token":"…","ticket":"…"}). The optional ticket is omitted
or null until verification succeeds; tokens without tickets remain usable by
self-hosted fcm, but not the licensed push gateway. When the FCM token changes,
the app discards the old ticket and verifies the new token. Computers paired
through a relay also register the token at the
relay, scoped to that pairing’s channel; that path does not use gateway tickets.
The daemon’s licensed push and self-hosted fcm backends can reach relay-paired
phones as well as direct/Tailscale phones; relay push: wake or push: title
wake-ups remain independent. Token refresh is synchronized while the app is
running, and on the next launch after an Android background refresh; pairing
the same computer again registers again. Registration retries when the daemon
or relay is offline. Unpairing attempts removal from both daemon and relay;
revoking the device always deletes the daemon registration.
A relay wake-up carries no request id. It shows the relay’s title (“Approval
requested” unless the computer uses push: title) with Open handup to
review, and tapping it opens the inbox; the next inbox sync clears it. For
wake-ups to reach the app, the relay’s FCM service account must belong to the
same Firebase project as the APK, as with the daemon’s fcm backend.
FCM uses two system channels: Approval requests (requests, default
importance) and High-risk approvals (high_risk, high importance), separate
from the outbox’s Sending decisions channel.
Android controls sound, lock-screen display, and heads-up eligibility per
channel. Push messages are high-priority, data-only; the app constructs the
notification even when its activity is not running. Swiping the app away is
supported; Android’s explicit Force stop prevents FCM delivery until the app
is opened again.
For the self-hosted fcm backend, notifications.fcm.payload: title (default)
sends the redacted title, request id, and risk; wake substitutes the generic
“Approval requested” title. For the licensed push backend,
notifications.push.payload: wake is the default and omits the title;
title opts into the redacted title. Neither sends preview content.
Google can see push metadata, and the gateway also sees it when using push;
relay end-to-end encryption does not cover either notification path.
The usual notification rules and quiet hours apply. Decide, cancel, and expiry send a
resolved message to cancel the matching notification, even during quiet hours.
Android can delay that message while the app is closed, so the app also clears
a request’s notification as soon as you tap its decision (not after the undo
window or delivery; Undo keeps the request in the inbox but does not bring the
notification back) and, whenever its queue syncs (including when it is opened or
brought back), clears those that are no longer pending.
Tapping a notification opens the request via handup://r/<id>. Push contains no
Approve/Deny actions.
Deep links and ntfy
Section titled “Deep links and ntfy”The app handles handup://r/<request id> and opens that request:
adb shell am start -a android.intent.action.VIEW -d handup://r/01M3S8C6H0CP6R88FFXM4NPFSFThe ntfy backend adds an Open action
with this link to every notification, so tapping Open in the ntfy Android
app opens the request in handup. When remote access is on, tapping the
notification itself (click) opens the web inbox (<web UI>/#/r/<id>)
in the browser instead. Releases from v0.1.2 include the web inbox; v0.1.1
and earlier do not, so upgrade before using notification browser links.
ntfy remains an optional alternative; native FCM is Android-only.
Native APNs delivery from the daemon is not implemented.
No native iOS app yet, and no TestFlight or App Store download.
The alternative is the daemon’s web inbox over Tailscale:
pair from Safari using the handup pair QR code and add it to the Home Screen.
It lacks native biometric confirmation and deep links, but has the same inbox.
Releases from v0.1.2 include the web inbox. v0.1.1 and earlier do not,
so upgrade to use an iPhone to approve requests.