hermesone

Installer and updater for the Hermes One desktop app (released from fathah/hermes-desktop). It detects your OS and architecture, downloads the matching release, verifies its sha512 checksum, and installs it (on macOS the signed app goes straight into /Applications, ready to launch).

Install

npm install hermesone

Installing the npm package does not download or launch the desktop installer. Running a native installer as a silent side effect of npm install is surprising, so that step is explicit and opt-in. After installing the package, run:

npx hermesone plan       # preview what would be downloaded (no changes)
npx hermesone install    # download + verify + launch the installer

To opt into the old auto-install behavior, set HERMESONE_AUTO_INSTALL=1 before npm install. Set HERMESONE_SKIP_INSTALL=1 to silence the postinstall notice entirely.

Global install

npm install -g hermesone

Exposes the hermesone command on your PATH:

hermesone plan
hermesone install
hermesone update
hermesone version

CLI

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. | | plan [tag] | Show what would be downloaded (tag, asset, size, expected checksum) — no changes. | | add <type/id> | Install a registry entry (skill / mcp / agent / workflow) into Hermes. | | version | Print the currently installed Hermes One version. | | help | Show usage. |

The installed app version is tracked in ~/.hermesone/state.json.

Installing registry entries (add)

hermesone add <type>/<id> installs an entry from the Hermes registry into your local Hermes setup — the same place the Hermes desktop app and Python agent read from. The command also pings the registry so the entry's public download counter ticks.

hermesone add mcp/github
hermesone add skill/plan
hermesone add agent/code-reviewer
hermesone add workflow/pr-triage

The <type> is one of skill, mcp, agent, workflow; the <id> is the entry id — usually one segment (plan, github), but it may be namespaced with / (e.g. an author/name entry).

| Type | Where it lands | | ---------- | ------------------------------------------------------------------- | | skill | <profile>/skills/<category>/<id>/ (entry folder downloaded) | | mcp | a server block under mcp_servers: in <profile>/config.yaml | | workflow | <profile>/workflows/<id>/ (entry folder downloaded) | | agent | a cloned Hermes profile named <id>, with the agent's AGENT.md as its SOUL.md |

<profile> is the active Hermes profile (~/.hermes for default, ~/.hermes/profiles/<name> otherwise). Use --profile <name> to target a specific one. Installing an agent requires the Hermes agent CLI to be present.

Relevant env:

• HERMES_HOME — Hermes data directory (default ~/.hermes; %LOCALAPPDATA%\hermes on Windows).
• HERMESONE_REGISTRY — registry web base URL (default https://registry.hermesone.org). The download-count call is best-effort: if the registry is unreachable, the install still succeeds.

Interactive UX

In an interactive terminal, install shows the release/asset/size/checksum, asks for confirmation, then renders a live spinner with a download progress bar and per-step status (resolve → download → verify → install). In a non-interactive context (CI, pipes, agents) it skips the prompt, prints plain status lines, and never blocks — pass -y/--yes to be explicit. Honors NO_COLOR.

Pinning a release

By default, install/update resolve the latest GitHub release. Pin a specific desktop release with the [tag] argument or the HERMESONE_VERSION env var:

hermesone install v1.2.3
HERMESONE_VERSION=v1.2.3 hermesone install

Platform behavior

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

Checksum verification

Every download is verified against the base64 sha512 published in the release's electron-builder manifest (latest-mac.yml / latest.yml / latest-linux.yml). If the hash does not match, the file is deleted and nothing is launched or installed. If a release publishes no checksum for the asset, install refuses to run unless you explicitly set HERMESONE_ALLOW_UNVERIFIED=1.

macOS uses the signed/notarized -mac.zip (which the manifest checksums) rather than the .dmg, so the install is both verifiable and drag-free.

Programmatic API

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

// Preview without downloading the installer.
const p = await plan();                 // { tag, asset, url, size, sha512 }

// Install (verifies sha512 before launching). Optionally pin a tag.
await install();
await install({ tag: "v1.2.3" });

// Update only if a newer release exists.
await update();

const current = await getInstalledVersion();

Registry installs:

import { add, fetchEntry, reportInstall } from "hermesone";

// Install a registry entry and bump its download count.
const res = await add("mcp/github");   // { type, id, name, installedTo, downloads }

// Lower-level helpers.
const entry = await fetchEntry("skill", "software-development/plan");
const count = await reportInstall("mcp", "github");   // number | null

License

ISC