Skip to content
handupbeta
Download

Install handup from compiled binaries and packages

View as Markdown

handup ships as compiled binaries and packages from its public release host, github.com/gethandup/handup. Downloads are public; you never need the application source, Git, Rust, Make or an Android SDK.

A handup Personal license is $30 USD one-time plus tax where applicable, sold through Polar (merchant of record): one person on their own machines, perpetual use and all future released updates. Polar emails the order confirmation; click handup license key under Included benefits to open the key in Polar’s customer portal (Find your key). Refunds are available within 30 days of purchase; see the Terms and Privacy Policy. No hosted service, unlimited personal support or indefinite development is promised.

Every release works fully for a 14-day trial; then activate your key with handup license activate KEY or Settings → License. Activation contacts gethandup.dev once, after which the license works offline. See License and trial.

If checkout reports too many attempts, wait about a minute before trying again. The server rejects the attempt before contacting Polar; nothing was charged.

After installing, run handup setup. It starts handup and connects your agents; see the quick start.

Platform Package Status
Linux x86-64 / ARM64 install script, Arch package, .deb, .rpm, Alpine .apk, tar.gz Primary platform.
Linux desktop app, x86-64 AppImage, .deb, .rpm Beta; needs the CLI daemon installed too.
macOS Intel / Apple Silicon Homebrew cask, tar.gz Beta; not notarized.
macOS desktop app (universal) .dmg Beta; not notarized; needs the CLI daemon installed too.
Android APK (sideload) Beta companion app for the daemon on your computer.
Windows x86-64 zip Beta; CLI and daemon, no background service.
Windows desktop app, x86-64 NSIS installer (.exe) Beta; not code-signed; bundles the CLI daemon.
Self-hosted relay, Linux x86-64 / ARM64 server tar.gz (from v0.1.7) Optional; see Self-hosted relay.

There is no iPhone app yet. See Windows for the Windows beta. Releases from v0.1.2 include the web inbox that iPhone and other browsers use; v0.1.1 and earlier do not.

For glibc-based Linux distributions, such as Debian, Ubuntu, Fedora and Arch. Alpine uses musl; use the Alpine APK package instead of this script.

Terminal window
curl -fsSL https://github.com/gethandup/handup/releases/latest/download/install.sh | sh

The script detects your OS and CPU (x86-64 or ARM64), downloads the matching handup_<version>_<os>_<arch>.tar.gz, verifies it against the release checksums.txt (SHA-256) and installs handup to ~/.local/bin. When minisign is installed and the release has a signature, it verifies that signature first and refuses to install if it is invalid. Without minisign, or for older releases without a signature, it prints a note and still checks SHA-256. It never uses sudo and refuses to install if the checksum is missing or wrong.

Variable Default Purpose
HANDUP_INSTALL_DIR ~/.local/bin Install directory (must be writable).
HANDUP_VERSION latest Release tag to install, e.g. v0.1.0.

Download handup-<version>-1-x86_64.pkg.tar.zst (or -aarch64), then:

Terminal window
sudo pacman -U ./handup-*.pkg.tar.zst

It installs the released binary as /usr/bin/handup. There is no AUR package.

Download handup_<version>_amd64.deb (or _arm64.deb) from the release, then:

Terminal window
sudo apt install ./handup_*.deb

Download handup-<version>-1.x86_64.rpm (or .aarch64.rpm), then:

Terminal window
sudo dnf install ./handup-*.rpm

Download handup_<version>_x86_64.apk or handup_<version>_aarch64.apk from the release for your CPU. This Alpine APK contains a musl build; the glibc archive used by the install script does not run on Alpine. It is not signed with an Alpine key, so verify its checksum first (below), then:

Terminal window
sudo apk add --allow-untrusted ./handup_*.apk

Download handup-desktop_<version>_amd64.AppImage (or the desktop .deb/.rpm bundle), then:

Terminal window
chmod +x ./handup-desktop_*.AppImage && ./handup-desktop_*.AppImage

The desktop app is an inbox for the handup daemon; install the CLI with one of the methods above as well. See desktop.

Terminal window
brew install --cask gethandup/tap/handup

The install script above also works on macOS. Builds exist for Intel and Apple Silicon. The binary is not notarized: the cask removes the download quarantine flag for you.

Download handup-desktop_<version>_universal.dmg (Intel and Apple Silicon), open it and drag handup to Applications. The app is not notarized, so macOS blocks the first open: remove the download quarantine flag once, then open it normally:

Terminal window
xattr -dr com.apple.quarantine /Applications/handup.app

Install the CLI as well (above); daemon notification banners on macOS need the desktop app. See desktop app on macOS.

Windows x86-64 is a beta. Each release has the desktop installer handup-desktop_<version>_amd64-setup.exe and the CLI zip handup_<version>_windows_amd64.zip; check them against checksums.txt like the other downloads.

Download those assets from the Windows downloads page or the public release. Do not run install.sh in PowerShell, Git Bash, MSYS or Cygwin: that script is for Linux and macOS. Inside WSL, use the Linux instructions for your distribution.

Run handup-desktop_<version>_amd64-setup.exe. It installs for your account only (no administrator prompt) to %LOCALAPPDATA%\handup, adds a Start menu entry and bundles handup.exe next to the app; the app starts the daemon on launch. The installer is not code-signed, so SmartScreen shows “Windows protected your PC” on first run: choose More info, then Run anyway. Uninstall from Settings › Apps. See desktop app for what is not supported on Windows yet.

Unzip handup_<version>_windows_amd64.zip, put handup.exe on your PATH (or add %LOCALAPPDATA%\handup from the desktop install), keeping the share folder beside handup.exe (it holds the web inbox), then start the daemon in its own terminal unless the desktop app is running:

Terminal window
handup serve

handup ask also starts it on demand (daemon.autostart). There is no background service: handup service install is not supported on Windows; to start handup at logon, run handup serve from a Task Scheduler logon task. The terminal inbox (handup inbox) works; handup ui opens the desktop app when handup-app.exe is next to handup.exe or on PATH.

Windows has no Unix socket: the CLI reaches the daemon on its loopback listener (daemon.listen, default 127.0.0.1:7465) with the bearer token in handup’s per-user state directory (%APPDATA%\handup\data unless HANDUP_STATE_DIR is set). handup gives its data and state directories and the token an owner-only ACL (you, SYSTEM and Administrators), repairs one it owns that other accounts can read, and refuses to start on such a directory owned by someone else; handup doctor reports whether they are private. Locking the ACL needs no administrator rights: run handup serve from a normal, unelevated terminal. Only one Windows user per machine can run the daemon on the default port; give others a different loopback daemon.listen, such as 127.0.0.1:7466. The configuration file is %USERPROFILE%\.config\handup\config.yaml. handup uses HOME when set and falls back to %USERPROFILE%, so handup setup, handup integrate and handup skill install work in a plain Windows session. The omp extension also works on Windows: see omp.

These Windows bugs are fixed for the next release. Until you can upgrade:

  • handup serve in a normal terminal fails with icacls exit 1300 while locking down its data folder. Run it from an administrator terminal.
  • Requests with file previews, or text previews too large to send inline, fail with “Access is denied”, as do handup config set, handup remote and changes saved in Settings. Edit config.yaml (above) directly instead: the daemon applies a saved file without a restart.
  • handup setup, handup integrate and handup skill install need HOME set: run $env:HOME = $env:USERPROFILE first in PowerShell.
  • The omp extension cannot reach the daemon (it looks for a Unix socket). Connect omp through MCP instead: handup integrate mcp --client omp (with HOME set as above).
  • handup ask, handup mcp, handup wait and other commands that start the daemon on demand hang when their output is captured by a pipe, as in an agent’s shell or a script, and handup ui does the same when it launches the desktop app. The background daemon keeps the pipe open, so the command never finishes. Start the daemon first so nothing has to start it: run handup serve in its own terminal, or open the desktop app.

Download handup-android_<version>_arm64.apk on the phone, allow your browser to install unknown apps when Android asks, and open it. Pair it with handup pair on the computer. See mobile, which also links an Obtainium setup for automatic APK updates.

From v0.1.7, releases also include the optional end-to-end encrypted relay for your own Linux server: handup-relay_<version>_linux_amd64.tar.gz or handup-relay_<version>_linux_arm64.tar.gz. Choose the server’s architecture, not this computer’s. Each is a static (musl) build with the handup-relay binary, LICENSE and THIRD_PARTY_NOTICES.md; verify it like any other download (below). The website’s downloads page lists them under Self-hosted relay (Linux server). You need a relay only when a phone cannot reach your computer over Tailscale; see relay setup.

Every release publishes checksums.txt with SHA-256 sums for the downloads. Signed releases also publish checksums.txt.minisig. Install minisign, put both files next to your download, and verify the signature before checking the checksum:

Terminal window
curl -fsSLO https://github.com/gethandup/handup/releases/latest/download/checksums.txt
curl -fsSLO https://github.com/gethandup/handup/releases/latest/download/checksums.txt.minisig
minisign -Vm checksums.txt -P RWRmxfwgJLzyYHvZKxoWSd44lp0rN3pUKD4HVPJIfwntmiIFFWDPW8V/
sha256sum -c --ignore-missing checksums.txt # Linux
shasum -a 256 --ignore-missing -c checksums.txt # macOS

For an older release, replace latest/download with download/<tag>. The install script and Homebrew cask verify checksums for you.

Terminal window
handup setup # service, every detected agent, agent skill; --dry-run previews
handup doctor --json

handup setup runs handup service install, handup integrate all and handup skill install; see first-run setup. See agent setup to configure one agent at a time.

To decide from a phone, iPhone or another computer, pair it over Tailscale: see remote access for the Android app and use handup in a browser for the web inbox (included from v0.1.2).

Every update is a new binary release; see the changelog.

  • Install script: re-run the same one-liner. It upgrades only when the release is newer by SemVer precedence (a prerelease such as v1.2.0-rc.1 is older than v1.2.0), keeps the previous binary as handup.backup.<date> (newest three kept) and restores it if the new binary fails to start.
  • Debian/Fedora/Alpine/Arch: install the newer package file the same way.
  • Desktop app: install the newer AppImage, package or .dmg over the old one; on Windows, quit the app and run the newer installer.
  • Homebrew: brew upgrade --cask handup.
  • Android: install the newer APK over the old one, or let Obtainium do it.
  • Self-hosted relay: replace the handup-relay binary with the newer archive’s and restart the relay.

After updating the binary:

  1. Restart the daemon so it loads the new executable: systemctl --user restart handup.service on Linux, or launchctl kickstart -k "gui/$(id -u)/com.handup.daemon" on macOS. For a manually started daemon, stop it and run handup serve --foreground again. There is no handup service restart command.
  2. Reapply the current integration with handup integrate all (or your chosen agent target) and refresh the bundled skill with handup skill install.
  3. Restart your agent sessions and their handup MCP servers so they load the new binary and integration configuration; close and reopen the desktop app.
  4. Run handup doctor --json and handup version to check the updated setup.

Install script:

Terminal window
handup uninstall

or, without a working binary, curl -fsSL https://github.com/gethandup/handup/releases/latest/download/uninstall.sh | sh -s -- --yes. Both remove the binary from ~/.local/bin (or HANDUP_INSTALL_DIR) plus installer backups. Configuration and data are kept.

Packages: sudo pacman -R handup, sudo apt remove handup, sudo dnf remove handup, sudo apk del handup, brew uninstall --cask handup. Run handup service uninstall first if you installed the user service. Windows: uninstall the desktop app from Settings › Apps, or delete the unzipped handup.exe.

The application source stays private. Buying a personal license does not grant repository access or application-source modification rights. Public usage documentation, machine contracts and agent instructions are distributed separately from the application repository.

Some integrations and web assets necessarily include readable scripts; that is not publication of the complete application source. Third-party components retain their licenses, and distribution must satisfy their notice and any applicable source-offer requirements. Their license texts ship as THIRD_PARTY_NOTICES.md: in every CLI and relay archive, at /usr/share/doc/handup/THIRD_PARTY_NOTICES.md from the Linux packages, and as a bundled resource of the desktop app.