Create and manage approval requests with the CLI
Request limits, exit codes, timeouts, storage paths, the daemon API, and
notification and configuration details. handup help COMMAND describes every
flag.
Commands
Section titled “Commands”handup serve --foreground # unix socket + authenticated loopback APIhandup ask --title "Review README" --preview text:README.md --wait --jsonhandup ask --title "Run a command" --command "echo hello" --timeout 10mhandup ask --title "Run tests" --command "make test" --run-timeout 30m # desktop Run limithandup ask --title "Review changes" --git-diff HEAD --waithandup notify --title "Deploy finished" --summary "All checks passed" # notice: no reply, returns at oncehandup ask --request - --wait --json # full request JSON on stdinhandup ls --status pending --jsonhandup show <id> --jsonhandup status <id> --jsonhandup wait <id> --jsonhandup approve <id> --option approve -m "Looks good"handup approve <id> --scope session # also project or alwayshandup deny <id> -m "Please revise the migration"handup cancel <id>handup delete <id>... --yes --json # permanently remove requests; pending ones cancel firsthandup stop <id> # stop a command the desktop app is running for ithandup schema request # or decision, event, openapihandup service install --dry-run # inspect unit/plist without writing/enablinghandup service install # install and start user servicehandup service statushandup service uninstallhandup demo --json # one sample request per available preview typehandup doctor --json # OK/WARN/FAIL diagnosticshandup inbox # live terminal inbox (requires a TTY)handup rules listhandup rules test request.json # or a request IDhandup rules rm <rule-id>handup log --json # retained audit events, newest firsthandup storage --json # disk use by category, retention, last cleanuphandup storage clean history --older-than 30d # background cleanup; or files, --allhandup license status # trial days left or license; activate KEY | import FILE | deactivatehandup remote tailscale # enable Tailscale access; restart daemon if needed, print URLhandup remote off # disable remote listener; keep devices pairedhandup pair --scope decide # QR pairing; offers Tailscale setup on a terminal if access is offhandup pair --relay # uses the configured relay, even with remote.mode offhandup devices list # enabled/disabled and push state; --json includes enabled and pushhandup devices disable <id> # pause access and push without unpairinghandup devices enable <id> # resume the same pairinghandup devices mute <id> # stop push notifications, keep API/event accesshandup devices unmute <id> # resume push notificationshandup devices scope <id> view # read-only; use decide to restore decision accesshandup devices revoke <id> # permanently unpairhandup yolo on --for 1h # auto-approve new low/medium risk (hard: all); handup yolo offhandup flood # sources sending a flood of requests, with mute/clear commandshandup flood clear --agent A --session S # dismiss its notices, deny its other pending requestshandup mute --agent A --for 1h # silence a source's notifications (--session, --dismiss-notices); bare: listhandup unmute <id> # or --allhandup report # support page in the browser; --feature, --question, --printhandup version --plain # alias: handup vhandup config init # --force overwrites existing confighandup config show|path|edit|keyshandup config show --effective # every setting, marked file or defaulthandup config get no_colorhandup config set output_format jsonhandup config unset output_format # back to the defaulthandup config toggle no_colorhandup config validate # check the active config, or a given pathhandup setup # first run: service, every detected agent, agent skill; --dry-runhandup integrate all # every detected agent: Claude Code, Codex, Cursor, omphandup integrate --list # detected agent homes and installed handup entrieshandup prompt # generic instructions; --agent claude|codex|cursor|omp tailors themhandup skill install # bundled agent skill; --agent claude|codex, --project, --dir, --dry-runhandup skill uninstall # removes only a handup-installed skillhandup completion zsh # bash, zsh, fish, powershell, elvishhandup uninstall # --yes skips confirmationask starts the daemon automatically when its socket is absent unless
daemon.autostart is false.
Delete specific requests
Section titled “Delete specific requests”handup delete <id>... [--yes] [--json] permanently removes the named pending
or resolved requests, their audit rows, and preview blobs no remaining request
uses. Pending requests are cancelled first: an agent already waiting on one
receives cancelled, never approval. Deleted requests no longer appear in
Inbox or History, and later status/show calls cannot recover them.
The CLI validates all IDs as ULIDs before deleting. On a terminal it asks
Permanently delete N request(s)? Pending ones are cancelled first. [y/N];
only an explicit yes continues. Without a terminal, --yes is required.
Deletion cannot be undone. This is a human cleanup control, not an agent’s
replacement for cancel (which preserves the request and audit).
--json prints {"deleted":["ID"],"missing":[]}; text output prints
deleted<TAB>ID and reports missing IDs on stderr. Exit 0 means every named
request was found and removed; exit 4 means confirmation was declined, an ID
was invalid/missing, or the operation failed. Found requests can be removed
even when other IDs are missing. The CLI sends batches of at most 1000 IDs;
an error in a later batch does not restore earlier deletions. For age/count
cleanup of resolved requests only, use storage clean.
First-run setup
Section titled “First-run setup”handup setup [--dry-run] runs the first-run steps in order and prints one
line per step:
handup service install: installs and starts the user service. Without a systemd or launchd user session, and always on Windows, it is skipped; runhandup serve, or rely onhandup askautostarting the daemon. An active service is left as is, and the step is skipped when a daemon already runs outside the service.handup service installitself keeps a changed service file as.bak; on Windowshandup serviceexits with an error.handup integrate all: connects every detected agent, as described below.handup skill install: installs the generic skill and, when Claude Code or Codex is detected, their agent-specific copies. An existing skill directory that handup did not install is left alone and reported as skipped.- Waits up to 5 seconds for the daemon to answer.
It is safe to run again: the service, connected agents and handup-owned skills
are refreshed in place. --dry-run previews every step without writing files
or starting the service. Exit 0 means every step succeeded or was skipped;
exit 4 means a step failed, and its line names the command to fix it.
With Tailscale connected and remote access off, the final hint suggests
handup remote tailscale, then handup pair.
Remote access and pairing
Section titled “Remote access and pairing”handup remote tailscale checks tailscale ip -4, validates the settings,
and sets remote.mode: tailscale only when needed. Missing or disconnected
Tailscale fails before any config write, with install or sign-in instructions.
It restarts through systemd/launchd when the user service owns the running
daemon; otherwise, on Linux and macOS, it stops and autostarts the daemon.
It checks that the daemon reports the requested mode, then prints the URL and
Next: run handup pair. If config and the running daemon already use
Tailscale, it does not restart. handup never changes your Tailscale configuration.
handup remote off sets the mode to off and applies it the same way; paired
devices stay paired. On Windows, switching a running daemon asks you to quit
it and run handup serve again.
For non-relay pairing when remote access is off, handup pair on a terminal
with Tailscale connected asks Turn on remote access over Tailscale now? [Y/n].
Enter or y enables access and continues pairing. With --json, no terminal,
or a declined prompt, it exits with an error telling you to run
handup remote tailscale. Without Tailscale, it explains how to set it up or
use handup pair --relay with a configured relay.
If remote.mode is already tailscale and remote.bind is empty, a daemon
started before Tailscale connects keeps serving locally and retries discovery
every 5 seconds rather than exiting. Non-relay handup pair reports that
remote access is waiting for Tailscale (the local pairing API returns 409).
Run sudo tailscale up on Linux or open the Tailscale app elsewhere, then
retry pairing; the remote listener binds automatically without a handup restart.
The doctor’s remote row in Tailscale mode checks the discovered tailnet
address (or remote.bind) and a TCP connection to remote.port (2-second
timeout). Missing/disconnected Tailscale or “nothing answers” produces WARN
with a fix and handup remote tailscale; this is not a phone reachability
test. With mode off and Tailscale connected, it suggests enabling access.
See Remote access for setup and manual configuration.
Agent integration
Section titled “Agent integration”handup integrate all [--dry-run] [--uninstall] [--no-mcp] uses the same
agent-home detection as --list:
- Claude Code:
~/.claude/or~/.claude.json. - Codex:
$CODEX_HOME/, default~/.codex/. - Cursor:
~/.cursor/. - omp:
$PI_CODING_AGENT_DIR/, default~/.omp/agent/.
Missing config files in detected homes are created by the normal installer.
It installs hooks plus MCP for Claude Code and Codex, and MCP only for Cursor
and omp. For omp, an existing extensions/handup.ts is upgraded safely; no
tool-gating extension is added by default. A customized or unknown
extensions/handup.ts fails validation, so no agent is written until you move
it aside. Add gating explicitly with
handup integrate omp (see omp for the approval policy).
--no-mcp keeps hooks/existing extensions only and skips Cursor and MCP-only
omp. Individual targets remain claude, codex, omp and
mcp --client claude-code|codex|cursor|omp.
All selected agents are validated before any file is written. Invalid config
aborts all writes, but validation continues to report every failed agent.
Successful plans retain the per-target diffs, backups and idempotent reapply;
--dry-run displays valid agents’ proposed changes even if another agent fails
validation, without writing. A write failure names the failing file and does
not stop attempts for remaining agents. Writes are not transactional, even
within one agent: a failure can leave that agent half-written; idempotent
reapply completes it after the cause is fixed. Config symlinks and existing
permissions are preserved, JSON key order is retained, and files changed since
planning are refused with “changed during install” instead of overwritten.
The final summary reports each agent as installed, already up to date, removed,
skipped or failed; dry-run outcomes are marked as previews.
--uninstall selects every agent with an installed handup entry. Exit 0 means
success, including no detected agents or nothing installed; exit 4 means an
agent failed. --client and --list are rejected with all (exit 4). Bare
handup integrate requires a target and suggests all or --list.
Exit codes and output
Section titled “Exit codes and output”| Exit | Meaning |
|---|---|
| 0 | approved/answered/dismissed, or successfully submitted/pending |
| 1 | denied |
| 2 | expired |
| 3 | cancelled |
| 4 | error |
| 5 | ran in the desktop app |
| 6 | license required |
The status codes apply to ask, wait, status, show, approve, deny,
and cancel; ls returns 0 on success. delete returns 0 on complete success
or 4 on missing IDs, refusal or failure; its JSON is a deletion report, not a
Request. Non-TTY queue commands never prompt or print banners; delete
requires --yes instead.
Exit 6 means the trial ended or the license was revoked; see License.
When one agent session already created requests.max_per_minute requests
(default 120) in the last minute, ask exits 4 with daemon HTTP 429 Too Many Requests and "code": "rate_limited"; see floods and mutes.
ask --wait --json and wait --json print the decision (including feedback and
content_hash) with id and status; a cancellation prints those three fields.
Other queue commands print Request JSON, except ls (a list) and delete
(the report above). --option id:label[:approve|deny] adds custom choices
(default outcome approve, except id deny). The id ends at the first colon and
a trailing :approve or :deny is the outcome; everything between is the
label, so it may contain colons (--option "a:Option A: fast"). A label that
itself ends in :approve or :deny needs an explicit outcome
(--option "run:Run:deny:approve" is the label Run:deny).
handup notify --title T [--summary S] [--preview TYPE:PATH]... [--session ID] [--session-title NAME] [--timeout D] [--dedupe-key K] [--agent A] [--cwd DIR] [--json] is the CLI form of the MCP notify tool: it submits a kind: info
notice (the same request as ask --kind info), prints it and exits 0 at once.
Put the message text in --summary under the one-line --title; there is no
body or message option. Previews use the same TYPE:PATH syntax as ask.
--kind info submits a notice that needs no reply: it gets OK (ok,
approve outcome) and Dismiss (dismiss, deny outcome) options,
on_timeout: expire, and takes no input. YOLO never decides it; only a
person, a dismiss rule or a mute
with --dismiss-notices dismisses it.
Either choice records status: dismissed (exit 0); decision.option says which.
Do not --wait on a notice; handup notify never waits, and agents with MCP can call the notify tool. A human’s optional
reply is delivered once through POST /v1/notice-replies (MCP, the omp
extension and Claude Code hooks claim it; see
notice replies).
Desktop Run decisions carry run_result. handup wait ID --json (and
ask --wait --json) includes it at the top level beside id and status;
handup status ID --json includes it under decision.run_result in the full
Request. Text output from wait prints a run summary: exit code or error,
duration, elevation and the last 40 lines of each redacted output tail, followed
by human feedback when present; text status shows the request and previews, so
use status --json for the result. Run is an approval even when execution fails,
but ask --wait, wait, status and show exit 5 for a decision carrying
run_result, regardless of the command’s own exit code. Read
run_result.exit_code and error, and do not run the command again.
See MCP’s result contract for the fields.
Previews and limits
Section titled “Previews and limits”Preview types: text, markdown, code, diff, files, command, json,
html, image, video, audio, file, pdf, and email. Repeat
--preview TYPE:PATH, or use TYPE:- for stdin. email:FILE reads an email
draft JSON object and also sets it as the editable input (see
email drafts). Files are uploaded as
immutable, SHA-256-addressed blobs. Directories use files previews; an
index.html becomes the bundle entry. Symlinks inside a bundled directory are
rejected; a symlink given as the preview path itself is followed. --command adds a
shell snapshot; submitting it does not execute it. The human can explicitly
choose Run in the desktop app. --git-diff [RANGE]
snapshots Git’s unified diff. MIME is sniffed from bytes and extensions.
Inline JSON-request previews over previews.inline_max (64 KiB) move into
blobs. Limits: 512-byte title, 64 KiB summary/input, 64 previews, 32 choices,
4096 bundle files, 16 MiB inline preview. previews.max_file_bytes defaults to
268435456 (256 MiB) and caps uploads and previews with a known size; oversized
uploads return 413 naming that key. CLI file and stdin previews also stop at a
fixed 256 MiB even if that key is raised. The remote listener still has its own
1 MiB request-body limit. Questions: 4096-byte question text and option
descriptions, 32 options, 16 KiB option previews and answer text. Email drafts:
500 recipients, 64 attachments, 998-byte subject.
GET /v1/blobs/{hash}/poster returns a JPEG still (at most 640 px wide, taken
at 0.5 s) of a video blob, so clients can show a poster before playback starts.
The daemon makes it with ffmpeg on first request and caches it under its data
directory until retention removes the blob. It answers 404 for non-video
blobs, when ffmpeg is not on PATH or cannot decode the file, and when
previews.video_posters is false (default true; applies live), and 410
like the blob route once retention removed the file.
Sources auto-detect cwd, Git root/branch and host. --agent, --session, and
--cwd override self-declared, unverified provenance, including with
--request -; explicit JSON source fields are otherwise preserved.
Timeouts, dedupe and durability
Section titled “Timeouts, dedupe and durability”Requests wait for a human by default (requests.default_timeout: none).
--timeout or a configured duration opts into expiry. --on-timeout deny
(default) records an expired, denied decision; expire expires without
approving; approve explicitly opts into automatic approval. Identical pending
requests with the same --dedupe-key collapse into one ID. Pending requests
and decisions survive daemon restart, and audit rows cannot be updated or
deleted.
Run limits
Section titled “Run limits”A desktop Run is stopped when it reaches its limit:
the request’s run_timeout (ask --run-timeout 30m, MCP request_approval
run_timeout, or the request JSON field), else run.timeout (default 10m),
never more than run.max_timeout (default 1h). Both are humantime durations
between 1ms and one year (as is run_timeout), apply live, and run.timeout
must not exceed run.max_timeout. run_timeout
is separate from the request’s decision timeout. The claim’s run.timeout_ms
holds the limit in force; its lease ends 2 minutes after it.
handup stop ID [--json] asks the desktop running the request’s command to
stop it (POST /v1/requests/{id}/run/stop); it prints the request with
run.stop set. The desktop sends SIGTERM, then SIGKILL after 5 seconds, and
reports stopped from this computer; terminated (or killed) as run_result.
It fails with 409 not running in the desktop app when nothing runs. See
stop from another device.
Configuration
Section titled “Configuration”Config path: --config > HANDUP_CONFIG > $XDG_CONFIG_HOME/handup/config.yaml
(default ~/.config/handup/config.yaml; on Windows
%USERPROFILE%\.config\handup\config.yaml when HOME is unset; ~ in agent
config paths and rule globs follows the same fallback). A missing file uses defaults;
handup config init seeds commented examples. handup config keys lists the
keys config get/set/unset accept, including every remappable keys.<id>
action, its label and default shortcut. remote.relay.allow_plaintext_lan
is a validated boolean (default false); the other relay settings are
edited in YAML (handup config edit), see relay.
| Command | Effect |
|---|---|
config show [--effective] [--json] |
Print the file; --effective lists every setting as built-in defaults merged with the file, each line key: value # file or # default, including the client preferences output_format (text), no_color (false) and display.theme (auto) |
config get <key> [--json] |
Print one value; JSON {"key": "...", "value": ...} (null when unset) |
config keys [--json] |
List settable keys; JSON array of {key, type, description} |
config set <key> <value> |
Validate and write one override |
config unset <key> |
Remove an override so the default applies (empty parent maps are pruned); prints “is not set” when absent |
config toggle <key> |
Flip a boolean |
config edit |
Edit a temp copy in $VISUAL/$EDITOR, validate on close, then replace the file |
config validate [path] |
Check a file (default: the active config) with the daemon’s own validation |
set, unset, toggle and edit write through the daemon’s validated atomic
writer: an invalid change writes nothing, a saved change is synced to disk, and a
symlinked config.yaml is written through to its target (the link stays). They
print the changed dotted keys and then what happened: “No daemon running: the
change applies when it starts.”; “The running daemon uses <path>; this file
applies when a daemon starts with it.” when --config/HANDUP_CONFIG names a
different file than the running daemon’s; once the daemon watching this file has
handled the saved content (checked via GET /v1/config/status for up to 3 s),
“Applied live: …” and/or “Restart the daemon to apply: …” (daemon.listen,
previews.max_file_bytes, remote.*), or “The running daemon kept its previous
config: path:line: message”; otherwise “The running daemon has not picked up this
save yet.” or “Could not read the running daemon’s config status; restart it to
be sure.”
config edit accepts editor arguments (EDITOR="code --wait") and starts from
the default template when the file is missing. Closing without changes prints
“No changes.”. An invalid result prints path:line: message and asks
[r]e-open or [d]iscard?; discard (or end of input) exits 2 and leaves the file
unchanged. config validate prints <path>: valid and exits 0, or prints
path:line: message on stderr and exits 2.
handup config show --effective --json # {"<dotted.key>": {"value": ..., "source": "file"|"default"}, ...}handup config get keys.approve --jsonhandup config unset requests.default_timeouthandup config validate ~/.config/handup/config.yaml.newhandup config set daemon.listen 127.0.0.1:7465handup config set requests.default_timeout 10mhandup config set run.timeout 30m # desktop Run limit; run.max_timeout caps ithandup config set notifications.type visualhandup config set notifications.quiet_hours 22:00-08:00handup config set notifications.backends '[desktop, push, ntfy]'handup config set notifications.ntfy.topic my-private-topichandup config set notifications.push.payload wake # default; no request titlehandup config set notifications.push.url https://push.gethandup.devhandup config set remote.mode tailscale # manual alternative; restart required, or use handup remote tailscalehandup config set history.keep_days 30 # 0 disables the age caphandup config set history.max_requests 500 # 0 disables the count caphandup config set history.max_bytes 1073741824 # best-effort 1 GiB live-storage caphandup config set history.files_keep_days 7 # files only; keep decisions/audithandup config set previews.max_file_bytes 268435456handup config set notifications.burst.max 20 # pings per source per window; 0 = offhandup config set requests.max_per_minute 120 # creation cap per source; 0 = offhandup config set decisions.primary_side left # Approve/Submit on the lefthandup config set keys.approve shift+yhandup config set keys.help f1handup config get keys.approveLive reload
Section titled “Live reload”The daemon watches its config file (atomic-rename saves from editors included)
and applies every save, whether from an editor, handup config set, Settings,
PUT /v1/keys or PUT /v1/storage/retention. Keys, rules, decisions.*,
notifications.*, previews.*, history.*, hooks, callbacks, requests.* and
all other settings apply live. Only daemon.listen, previews.max_file_bytes
and everything under remote (mode, bind, ports, relay) need a daemon restart;
until then they are reported as restart required.
Every save is validated first. An invalid file, including one whose rule ids
collide with a session rule, keeps the previous config, rules included, in force
and logs path:line: message until a valid save. A save made while the daemon is
starting is applied once the watcher starts. Each save
emits on /v1/events:
{"type":"config.changed","config":{"applied":["decisions.undo_window"],"restart_required":["daemon.listen"]}}error is set to path:line: message when the file is invalid. restart_required
lists every restart-only key changed since the daemon started, so it empties
again when a change is reverted. GET /v1/ui-settings carries the same state as
config_restart_required and config_error. GET /v1/config/status (local
listener only, not the remote one) returns {path, sha256, restart_required, error}: the config file the daemon loads and watches, the SHA-256 hex of the
content it last handled, pending restart-only keys and the file’s current error.
Clients refetch settings and show
a header notice beside the connection pill (its own row below the header on phones):
“Config reloaded” briefly, “Restart daemon to apply: …” until dismissed (it
returns once the set of restart-only keys changes or empties) or applied, and
“config.yaml invalid (line N), kept previous” until a valid save.
Credentials (Firebase and Google services JSON) stay in their own files; do not
put secrets in config.yaml.
Keyboard shortcut configuration
Section titled “Keyboard shortcut configuration”The daemon’s keys: map overrides desktop/web shortcuts by action id; omitted
actions keep their defaults. handup config keys lists the supported ids (for
example approve, deny, next, previous, search, help, and undo).
Inbox and History also support remappable last (default shift+g, with
built-in End), scroll_line_down / scroll_line_up (ctrl+e / ctrl+y),
scroll_half_down / scroll_half_up (ctrl+d / ctrl+u), and
scroll_page_down / scroll_page_up (pagedown / pageup). Scroll actions
move the request detail on screen, not the list. first is built in: press
g g (the second g within 1 second) or Home to jump to the first request;
keys.first cannot be overridden. Ctrl+F / Ctrl+B are not taken.
This does not change the terminal inbox’s keys.
pick (default x) picks or unpicks the cursor row for deletion, entering
select mode if needed. delete (default delete, with built-in Backspace)
asks to delete picked rows, or the cursor row when none are picked; it never
skips confirmation. Both are remappable list actions in Inbox and History,
unavailable in the quick window, Auto-handled, or on view-only devices.
keys: approve: shift+y help: f1To use Shift+J / Shift+K for half-screen scrolling, first free their default
selection-extension bindings by moving extend_next / extend_previous to
Shift+arrows. Save all four overrides together:
keys: scroll_half_down: shift+j scroll_half_up: shift+k extend_next: shift+down extend_previous: shift+upKeys are case-insensitive and normalized to lowercase. Combine mod, ctrl,
alt, meta, or shift with + and one key, such as shift+y, alt+a, or
mod+f2. mod means Command on macOS and Ctrl elsewhere; do not combine it
with ctrl or meta, and do not combine ctrl with meta. A key is one
printable ASCII character, f1–f12 (not f01), or enter, esc, space,
tab, backspace, delete, up, down, left, right, home, end,
pageup, pagedown, insert, or plus (for +). Shift combines with letters
and named keys other than plus; use the resulting symbol for punctuation
(?, not shift+/). Duplicate modifiers and unknown keys are rejected.
Two actions cannot use the same effective key in an overlapping view (Inbox
or History), including unchanged defaults and built-in keys. mod conflicts
with both the equivalent ctrl and meta binding, so the config works across
platforms. Disjoint-view actions may share a key. Built-in Esc, Enter,
arrows/Shift+arrows, g, Home/End, Space, Tab, Backspace, 1–9,
[/], {/}, and mod+enter remain reserved where they apply and cannot be remapped
(mod+shift+enter is free). g and Home are reserved for first, and
End for last even if last is remapped; Home/End also move through question
answers. A conflict with Home/End names first/last, respectively.
Backspace stays reserved for delete even when keys.delete is remapped.
Unknown action ids, malformed keys and
conflicts are refused without saving. To reuse a taken key, move the other
action first. Remove an override from YAML to restore that action’s default.
search defaults to / and opens/focuses Inbox search or focuses History search.
It is a list action, unavailable in the compact quick window or Auto-handled
view. Because it now overlaps Inbox actions, it cannot share their keys (for
example keys.search: a conflicts with Approve). Inbox search is hidden until
opened and combines with filters; see Inbox filters.
CLI/YAML edits apply live (see Live reload), and so does
Settings → Keyboard shortcuts; its editor needs a fine pointer and
local access or a paired device with decide scope. Overrides belong to the
computer, not one device. The sheet and button hints show the effective keys.
Shortcut API
Section titled “Shortcut API”GET /v1/ui-settings includes keys, the current override map (not all defaults).
PUT /v1/keys replaces the complete map:
{"keys":{"approve":"shift+y","help":"f1"}}Omitted actions revert to defaults; {"keys":{}} resets all. Local, remote HTTP
and relay tunnel routers expose the endpoint. Paired devices need decide
scope; view devices and submit tokens get 403. A successful response is 200
with {"keys":{...}} in canonical form. Unknown/built-in actions, invalid keys,
conflicts, or no daemon config file return 400. The daemon saves keys: to its
config and applies it without restarting, logs the actor (including the paired
device name/id), and emits {"type":"keys.changed","keys":{...}} (plus
config.changed) on /v1/events so open clients rebind. See OpenAPI.
Storage configuration
Section titled “Storage configuration”Storage settings accept nonnegative integer bytes/days, not size suffixes.
Storage settings apply live when the config is saved (handup config set history.*
or an editor); Settings → Storage in the desktop app also changes
keep_days/files_keep_days (see Storage usage and cleanup).
history.max_bytes defaults to 0 (no disk cap); history.files_keep_days
defaults to 0 (files live as long as their request). Retention runs at startup
and hourly, first applying the age/count caps, then file expiry and the byte cap.
history.keep_days: 0 (Forever in Settings) removes only the age cap;
history.max_requests (2000 by default) still bounds history.
The cap measures live database bytes ((page_count - freelist_count) * page_size),
WAL bytes after checkpoint/truncation, and blob files. It removes oldest resolved
requests first, never pending requests or files still needed by kept requests,
until under the cap or no resolved requests remain. handup doctor reports the
same live-storage measure. It is best-effort: pending data cannot be removed,
and hourly retention never shrinks the database file: freed pages stay as free
space that new requests reuse. Only a storage cleanup returns them, and only on
databases created with auto_vacuum=incremental (new databases since storage
cleanup shipped). File-only expiry preserves request and audit rows;
files shared with pending or newer resolved requests stay stored.
Expired blob/preview downloads return 410 Gone; the UI shows
“File no longer stored (history.files_keep_days)”.
output_format (text/json/yaml) is validated but no command reads it yet: queue
commands (ask, wait, status, ls, …) print JSON only with --json.
Themes: auto/light/dark. Primary side:
right (default)/left; each app may override it per device. Global --no-color and
NO_COLOR disable color; redirected output is plain.
Storage
Section titled “Storage”Linux data: $XDG_DATA_HOME/handup/handup.db (SQLite WAL) and
blobs/sha256/<2>/<62>; state: $XDG_STATE_HOME/handup/token (0600); socket:
$XDG_RUNTIME_DIR/handup/handup.sock (0600, parent 0700), falling back to the
state directory. macOS uses the platform application-support directory for
data and state. HANDUP_DATA_DIR, HANDUP_STATE_DIR, and HANDUP_SOCKET
override these paths. Existing data/state/socket-parent directories must already
be private (0700); shared directories and symlinks are rejected rather than
chmodded. A process lock prevents a second daemon on the same state directory.
The daemon creates and repairs its database and SQLite sidecar files to mode
0600 on open.
Storage usage and cleanup
Section titled “Storage usage and cleanup”handup storage shows the daemon’s disk use by category: History
(request rows with inline previews, resolutions and their indexes), Audit log,
Files (preview blobs on disk plus their metadata), Free (free database
pages, reused before the file grows) and Other (devices, tokens, schema and
the write-ahead log). The categories add up to the total. It also prints pending
and resolved counts, the retention policy and the running or last cleanup;
--json prints the GET /v1/storage report, which includes
oldest_resolved_at and compacts (whether cleanups can shrink the file).
handup storage clean history --older-than 30d # resolved requests, audit, unshared fileshandup storage clean files --older-than 1w # only files; decisions and audit stayhandup storage clean history --keep 100 # all but the newest 100 resolved requestshandup storage clean history --all --json # every resolved requestclean needs --older-than DURATION (at least 1d, rounded down to whole days),
--keep N (keep the newest N resolved requests; with --older-than, both
apply) or --all. Requests resolved in the same millisecond as the last one
kept stay too. It starts a background cleanup on the daemon, follows its progress
and prints what it removed; it exits 0 when the cleanup finished and 1 when it
was cancelled or failed. Pending requests are never touched, nor files a pending
(or, for files, a newer) request references. history deletes resolved
requests with their audit events and the files no remaining request uses;
files removes only files and keeps the metadata, so later downloads return 410
Gone. Only one cleanup runs at a time (409 otherwise). It works in small
batches, so requests and decisions keep flowing, then compacts the database where
supported. Stopping the CLI does not stop the cleanup; cancel it from Settings →
Storage or with POST /v1/storage/cleanup/{id}/cancel.
Storage endpoints (local, plus the paired-device scope noted):
| Endpoint | Purpose |
|---|---|
GET /v1/storage |
Usage, retention, running or last cleanup. view |
GET /v1/storage/estimate?target=history|files&older_than_days=N&keep_newest=N |
What a cleanup would remove now (requests, files, approximate bytes); 0/absent disables each limit (both = every resolved request). view |
POST /v1/storage/cleanup |
Body {target, older_than_days?, keep_newest?}; 202 with the job, 409 with the running job. decide |
GET /v1/storage/cleanup/{id} |
Progress: state (running, done, cancelled, failed), done/total, deleted counts, bytes_freed, compacting. view |
POST /v1/storage/cleanup/{id}/cancel |
Stops after the current batch; what was removed stays removed. decide |
PUT /v1/storage/retention |
Body {keep_days?, files_keep_days?} (0–36500, 0 = forever / with request). Saves to the daemon’s config file and applies without a restart; a shorter period starts a cleanup at once (job in the response, null if another cleanup runs). decide |
Only the running or most recent cleanup is kept, in memory; a daemon restart forgets it.
Daemon API
Section titled “Daemon API”API v1 covers health/OpenAPI, requests, long-poll wait, hash-bound decisions,
cancellation, permanent deletion, blob upload/Range download, and WebSocket /v1/events (pinged
every 25 s; return Pong or the server closes after two unanswered intervals).
The same API runs on the Unix socket and daemon.listen (default 127.0.0.1:7465). Unix
access relies on filesystem permissions. TCP requires a bearer token, a loopback
Host (localhost or any loopback IP), and an absent or trusted Origin (Tauri
origins or remote.web_origin). Windows has no Unix socket: local clients use
the TCP listener, whose address the daemon writes to daemon.addr in the state
directory next to token.
daemon.listen must be loopback; remote access is a separate listener
(remote.mode) that accepts paired device tokens and named submit tokens. See
remote access and the generated OpenAPI.
Delete requests
Section titled “Delete requests”POST /v1/requests/delete takes {"ids":["ID","OTHER_ID"]} and returns
200 with {"deleted":["ID"],"missing":["OTHER_ID"]}. A batch must contain
1–1000 IDs; empty or oversized batches return 400. Unknown body fields
are rejected. Missing IDs are reported, not a 404 for the whole batch;
duplicate IDs are processed once per call.
The daemon cancels each still-pending request, then removes the requests and
their audit rows in one transaction. Blobs shared with any remaining request
stay stored; orphaned preview blobs are removed. An agent already waiting on
a deleted pending request receives cancelled; subsequent reads return not
found. There is no undo.
The local Unix socket/authenticated loopback API, remote HTTP listener and
relay tunnel expose this route. Paired devices need decide scope and must
still be enabled with that scope when deletion commits; view-only devices
and submit tokens receive 403.
After commit, /v1/events sends request.cancelled for pending deletions
before request.deleted for the removed requests. A resolved deletion emits
only request.deleted; its request payload is the last stored snapshot,
not a request that remains readable.
Auto-handled read state
Section titled “Auto-handled read state”Mark read in the Auto-handled view shares a read watermark across every device connected to the same daemon, separately for each computer. The daemon persists it across restarts; it is not a per-device display preference.
| Endpoint | Contract |
|---|---|
GET /v1/auto-read |
200 with {"at":0} until first marked read, then the stored watermark. Remote/relay devices need view (included in decide) |
PUT /v1/auto-read |
Body {"at":123}; atomically stores max(stored, at) and returns 200 with {"at":stored}. Remote/relay devices need decide; view devices and submit tokens get 403 |
at is a nonnegative integer in the UI’s auto-decision timestamp unit, opaque
to the daemon. Values above 9223372036854775807 (i64::MAX) return 400
without changing state. Older or equal writes cannot lower the watermark and
emit no event. Only an increase emits {"type":"auto_read.changed","at":123}
on /v1/events, so other connected devices follow without a reload.
Local, remote HTTP and relay tunnel routers expose both methods.
Clients keep a per-computer local copy for offline use, merge incoming values by maximum, and send a higher local mark on resync. With an older daemon that returns 404 for this endpoint, read state remains device-local.
WebSocket events
Section titled “WebSocket events”GET /v1/events upgrades to a live event stream (paired remote/relay devices
need view, included in decide). Each JSON message has type and its payload:
type |
Payload |
|---|---|
request.created, request.decided, request.expired, request.cancelled |
request: the request with its current status; an auto-handled request arrives already decided |
request.updated |
request: desktop run started, stop requested, claim released or interrupted (request.run) |
request.deleted |
request: the removed request’s last snapshot; remove it from lists/caches. Pending deletions emit request.cancelled first |
yolo.changed |
yolo: the mode and timer after a change or timer expiry |
auto_read.changed |
at: the shared Auto-handled read watermark, only when it rises |
floods.changed |
floods: flooding sources after flooding or muted state changes |
mutes.changed |
mutes: active mutes after adding, removing or timer expiry |
keys.changed |
keys: the complete shortcut override map |
config.changed |
config: applied keys, restart-required keys and any validation error; see Live reload |
Clients should ignore unknown event types. The server pings every 25 seconds; return Pong or the connection closes after two unanswered intervals. These live UI events are separate from the lifecycle hook envelope.
Test requests
Section titled “Test requests”POST /v1/requests/test creates a fixed synthetic request to try the inbox and
notifications. Send no body or {} for an approval, or
{"kind":"approval"} / {"kind":"question"}. The daemon returns 201 with
the created ApprovalRequest; unknown kinds, extra fields, or malformed JSON
return 400. No custom title, source, preview, or other request fields are
accepted.
The server sets the title to Test request or Test question, agent to
handup, session to handup-test, risk to low, and timeout to 15m. The
question includes sample choices and free text. Approving, denying, or answering
performs no action. These samples use the normal request and decision flow.
The route exists on the local Unix socket/authenticated loopback listener,
remote HTTP listener, and relay tunnel. Remote paired devices need decide
scope; view devices and submit tokens receive 403. Arbitrary remote request
submission remains a separate submit-token capability.
curl --unix-socket "$XDG_RUNTIME_DIR/handup/handup.sock" \ -H 'Content-Type: application/json' http://handup/v1/requests/test \ -d '{"kind":"question"}'Notifications
Section titled “Notifications”Native notifications support sound/visual/both, new requests, critical
high-risk urgency on Linux (bypasses quiet hours), expiry warnings, reminders,
and quiet hours. Sound uses paplay (Linux) or afplay (macOS), with a
platform sound or notifications.sound_file. Notification text redacts common
credentials (including handup device tokens, license keys, and labeled relay
secrets) and includes the request ID. Linux notification actions follow
none|low_risk|all; macOS actions are not supported. Deny actions cannot bypass
a required-feedback policy. An info notice reads “Notice: title” with its
redacted summary as the body, and its actions are OK and Dismiss.
notifications.suppress_when_focused is reserved.
Each agent session raises at most notifications.burst.max notifications
(default 20) per notifications.burst.window (default 1m) on every backend,
then one summary; handup mute silences a source entirely. See
floods and mutes.
On macOS the daemon posts banners as the handup desktop app (handup.app), so
click Allow when macOS asks whether handup may send notifications. Without
handup.app installed (the CLI-only download) banners are posted as Finder and
macOS does not show them. Banners also stay hidden while Screen Sharing is
connected. See desktop app on macOS.
notifications.backends accepts desktop, ntfy, fcm, and push, and
defaults to [desktop, push]. The licensed push backend for the official
Android app is live at https://push.gethandup.dev. It requires an installed
signed license and registered phone tokens with proof-of-possession device
tickets; only verified phones get woken. No Firebase service-account key is
needed on the computer.
notifications.push.url defaults to https://push.gethandup.dev and requires
HTTPS (loopback HTTP only for local tests). notifications.push.payload is
wake by default (no request title), or title for the redacted title; neither
sends previews. The gateway sees the signed license, phone tokens, device tickets,
and routing metadata; Google sees the phone tokens and notification data.
Listing fcm as well
disables the gateway path; self-hosted FCM takes precedence even if its
credentials fail.
The ntfy backend sends only the title, risk, and a handup://r/<id> link
(never preview content unless ntfy.include_content); token_env names an
environment variable, not a secret value. See
notification backends. Lifecycle webhooks
live under top-level hooks: (event hooks).
The doctor’s push row names the push route: off, self-hosted FCM with the
registered-device count, or licensed gateway with license, verified/unverified
phones and whether the gateway answers. push-last shows the last delivery
result and its age (for example refused 5m ago: rate limited), and relay
checks that a configured relay answers. These rows only warn; network checks
time out after 3 seconds. See Android push.
handup doctor checks Linux GStreamer H.264, VP9, and Opus plugins and idle
detection support. It also warns when the daemon runs a different build than
the CLI (local GET /v1/version) and, on Linux, lists handup processes still
running a binary that was replaced on disk, such as a handup mcp server or the
daemon left over from before a binary upgrade; restart those. On Windows it
checks that the state directory and token are private: OK when only you,
SYSTEM and Administrators have access, WARN when the ACL is still inherited
(restart the daemon to lock it down), FAIL when other accounts have access. Daemon
replies ignore fields a client does not know, so older clients keep working
against a newer daemon, while request and decision input still rejects unknown
fields. handup demo creates PNG/WAV/HTML/diff/bundle/JSON/command/PDF
samples at runtime; video requires ffmpeg and is skipped when absent.
Uninstall
Section titled “Uninstall”handup uninstall removes the installed binary and backups and preserves
configuration. HANDUP_INSTALL_DIR overrides ~/.local/bin. See
downloads and releases for customer binary availability;
the private repository’s maintainer installer is not a customer source-access
or distribution requirement.