bankrbot/hermesone

Hermesone: Install & Update Hermes One

hermesone (v0.2.0) is the npm package that installs and updates the Hermes One desktop app. It detects the host OS/arch, downloads the matching GitHub release, verifies its sha512 checksum, and installs it — on macOS the signed app goes straight into /Applications, ready to launch (no drag step). It ships a CLI and a programmatic API.

⚠️ This installs and runs third-party native code on the user's machine. The package mitigates this — it verifies every download against the publisher's sha512 manifest (and refuses to run an unverified build), and in an interactive terminal it asks for confirmation first — but installing software is still a host-level action. See Safety & approval.

• Homepage: https://hermesone.org
• Package repository: https://github.com/hermesonehq/hermesonejs
• App releases pulled from: fathah/hermes-desktop (GitHub releases)

Naming: the app is Hermes One (formerly "Hermes Desktop"). The GitHub repo it's released from is still named fathah/hermes-desktop, and the installed macOS bundle is Hermes One.app — so you'll see both names. Use "Hermes One" with users; the hermes-desktop slug is just where the release assets live.

Why this lives in Bankr Skills. Hermes One is building toward an agent economy, with Bankr as the primary transaction layer for agent payments. This skill is the entry point: it gets Hermes One installed and current on the host so an agent can participate. Today the package does install/update/version only — no accounts, keys, or onchain actions. Bankr-settled transactions and agent-economy hooks are on the roadmap and will be documented here as they ship.

Safety & approval

Installing or updating Hermes One modifies the host. The package enforces two guardrails for you: it verifies sha512 before installing (fail-closed — it refuses if no published checksum is found), and on an interactive terminal it shows a confirmation prompt with the release, size, and checksum status. Still follow these rules:

• Require explicit user approval before any install or update. Never trigger one as a silent side effect of another task or an autonomous workflow.
• In non-interactive/agent contexts the confirm prompt is skipped (and --yes does the same). There, you are the approval gate: run hermesone plan first, show the user the resolved release/asset/size/sha512, get a yes, then run install.
• Don't override verification. Only set HERMESONE_ALLOW_UNVERIFIED=1 if the user explicitly accepts installing a build with no published checksum.
• Pin what you install (@0.2.0 for the package; a release tag for the app) when reproducibility matters — see Pinning.

Recommended flow

Installing the npm package no longer installs the app as a side effect (see Postinstall behavior). The clean path is: install the CLI, preview, then install on confirmation.

# 1. Install the CLI (no host change — the app is not installed yet).
npm install -g [email protected]

# 2. Preview the exact release that would be installed.
hermesone plan

# 3. Install. Interactive terminals show a confirmation prompt + live progress;
#    non-interactive contexts proceed (add --yes to be explicit) and print plain lines.
hermesone install

hermesone update is safe to run repeatedly — it no-ops when already current and only downloads when a newer release exists.

Preview a release

hermesone plan [tag] resolves and prints what would be installed — release tag, asset, size, and the expected sha512 — without downloading or installing anything. Use it to show the user before asking them to approve an install.

CLI reference

hermesone <command> [tag]

| Command | Description | | ---------------- | ------------------------------------------------------------------------------------ | | install [tag] | Download, verify (sha512), and install Hermes One — latest, or a pinned release tag. | | update [tag] | Update Hermes One if a newer release is available (no-op when current). | | plan [tag] | Show what would be downloaded (tag, asset, size, expected checksum). No changes. | | version | Print the installed Hermes One version, or a "not installed" message. | | help | Show usage. |

| Flag / Env | Effect | | ------------------------------ | ---------------------------------------------------------------------------- | | -y, --yes | Skip the confirmation prompt (for non-interactive/scripted installs). | | HERMESONE_VERSION=<tag> | Pin the release tag (same as the [tag] argument). | | HERMESONE_ALLOW_UNVERIFIED=1 | Proceed even if no published checksum is found. Not recommended. |

In an interactive terminal, install renders a confirmation box, a live download progress bar, and per-step status (resolve → download → verify → install). In a non-interactive context it prints plain status lines and never blocks. Color honors NO_COLOR.

What gets installed per OS

| OS | Artifact | Behavior | | ------- | -------------------- | ------------------------------------------------------------------------------------------------- | | macOS | *-mac.zip (signed) | Verified, unzipped, installed into /Applications (or ~/Applications), then launched — no drag. Updates replace in place. | | Windows | *-setup.exe | Verified, then the installer is launched. | | Linux | *.AppImage | Verified, marked executable, then launched. |

Pin a specific release

install/update use the latest release by default. To install a known build, pass a tag or set the env var:

hermesone install v0.6.35
HERMESONE_VERSION=v0.6.35 hermesone install

Checksum verification (built in)

Each download is verified against the base64 sha512 published in the release's electron-builder manifest (latest-mac.yml / latest.yml / latest-linux.yml). On mismatch the file is deleted and nothing is installed. If a release publishes no checksum for the asset, install refuses unless HERMESONE_ALLOW_UNVERIFIED=1 is set. You do not need to verify manually — surface the result from plan to the user and let the package enforce it.

Programmatic API

import { plan, install, update, getInstalledVersion } from "hermesone";

// Preview without downloading — show this to the user for approval.
const p = await plan();                       // { tag, asset, url, size, sha512 }

// Install (verifies sha512 before installing). Optionally pin a tag, and/or
// subscribe to progress events to render your own UI.
await install({
  tag: "v0.6.35",
  onProgress: (e) => console.log(e.phase),    // resolve|download|verify|extract|launch|installed...
});

await update();                                // no-op if already current
const current = await getInstalledVersion();   // e.g. "0.6.35", or null

Also exported: fetchRelease, parseChecksums, selectAsset, getTarget, isNewer, and types Release, ReleaseAsset, State, Target, InstallOptions, InstallPlan, ProgressEvent. The library prints nothing on its own — all output is driven by your onProgress handler.

Version tracking

• The installed version is detected from the app on disk first. On macOS this reads CFBundleShortVersionString from Hermes One.app/Contents/Info.plist (/Applications and ~/Applications), so manual installs are recognized too.
• Otherwise it falls back to ~/.hermesone/state.json, written after each install/update done through this tool.
• version returns null (CLI prints "Hermes One is not installed.") when neither source yields a version.

Postinstall behavior

npm install hermesone does not download or launch the app — running an installer as a silent side effect of npm install is surprising, so it's opt-in. After installing the package it prints the next step (npx hermesone install). Controls:

| Env (set before npm install) | Effect | | ------------------------------ | ---------------------------------------------------------------- | | (none) | Prints guidance; does not install the app. | | HERMESONE_AUTO_INSTALL=1 | Runs the install automatically during postinstall. | | HERMESONE_SKIP_INSTALL=1 | Silences the postinstall notice entirely. |

Troubleshooting

| Symptom | Cause / fix | | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | No published checksum found for <asset> | The release has no sha512 manifest entry for this asset. Prefer a release that does; only override with HERMESONE_ALLOW_UNVERIFIED=1 if the user accepts it. | | Checksum mismatch for <asset> | The download didn't match the published sha512 — the file was deleted and nothing installed. Retry; if it persists, the release/asset may be compromised or corrupted. | | Failed to fetch release ...: 403 | GitHub API rate limit (unauthenticated). Wait and retry. | | No Hermes One build available for <platform>/<arch> | The release has no asset for this OS/arch. Check the releases page. | | Prompt didn't appear / it just proceeded | Not a TTY (CI, pipe, agent). That's expected — it runs non-interactively. Use plan first to gate, or --yes to be explicit. | | version says not installed after a manual install | Only macOS auto-detects from disk. On Windows/Linux, install once via this tool so ~/.hermesone/state.json is written. |

Notes & guardrails

• Host-level code execution. Install/update download a native build from fathah/hermes-desktop and run it. The package verifies sha512 and (interactively) prompts, but only run it on explicit user intent — never automatically from an agent workflow.
• Preview, then install. Use plan to show the release/asset/size/sha512; in non-interactive contexts that preview is your approval gate.
• No credentials. The tool needs no API key or account and performs no onchain or payment actions.