Skip to content

HERMES_SURFACES.md

Latest commit

 

History

History
44 lines (38 loc) · 2.84 KB

HERMES_SURFACES.md

File metadata and controls

44 lines (38 loc) · 2.84 KB
Raw

Hermes Surfaces

Use this guide when deciding where to install Hermes XAPI and where to keep runtime credentials. Hermes XAPI uses one plugin entry point across Hermes Desktop, remote gateway profiles, the web dashboard, TUI, CLI, cron, and CI-style smoke tests. The difference is where the Hermes runtime executes.

Surface Install Hermes XAPI Configure TWEXAPI_KEY Notes
Desktop, local runtime Local machine running Desktop Local runtime environment or ~/.hermes/.env Use Desktop for review and explicit approvals.
Desktop, remote gateway profile Remote Hermes host Remote Hermes host environment or ~/.hermes/.env on that host The Desktop app is only the client surface.
Web dashboard Runtime host behind the dashboard Runtime host environment Dashboard credential pages do not replace plugin env gating.
TUI or CLI Machine running the command Same process environment or ~/.hermes/.env Run /reload after editing .env in an active CLI session.
Cron or unattended gateway Scheduled runtime host Service environment before process start Keep actions disabled unless the workflow has an approval step.
CI smoke test CI job environment Ephemeral secret store only when testing reads Prefer xapi_explore checks when no secret is available.

Readiness Checklist

  • Install with hermes plugins install twexapi-dev/hermes-xapi --enable, or run hermes plugins enable hermes-xapi after installation.
  • Confirm hermes plugins list shows hermes-xapi as enabled.
  • Confirm hermes tools list shows the hermes-xapi toolset.
  • Use xapi_explore first; it does not need TWEXAPI_KEY.
  • Use only catalog-listed paths; copied endpoint URLs must resolve to one.
  • Use docs/SUBMISSION_READINESS.md before proposing Hermes XAPI to public skill, plugin, catalog, registry, awesome-list, or integration surfaces.
  • Set TWEXAPI_KEY only on the host that executes plugin tools.
  • Keep HERMES_XAPI_ENABLE_ACTIONS=false for research, monitoring, support, launch checks, and other unattended sessions.
  • Leave HERMES_XAPI_ENABLE_ACTIONS=true unset for normal public-read work. Enable it only when an operator intentionally opts into a non-default gated session.

Common Mistakes

  • Installing Hermes XAPI only on a laptop while Desktop is connected to a remote gateway. Install on the remote Hermes host instead.
  • Pasting API keys into prompts, issues, PR comments, or tool arguments. Use the runtime environment or ~/.hermes/.env.
  • Testing slash commands with one-shot hermes -z "/xstatus". Use an active CLI, TUI, Desktop, or gateway session for /xstatus and /xtrends; use hermes -z for tool-call probes.
  • Treating install as enablement. Hermes discovers third-party plugins before it executes them, so enablement is a separate step unless --enable was used.