Skip to content
Agent

Server Setup

Agent connects directly to a Hermes server you control. The app and server integration are free; your hosting and model-provider costs are separate. These instructions cover the next beta, which is still in preparation.

1. Install compatible Hermes

The beta requires the reviewed Hermes compatibility release. It adds the native connection, ongoing conversations, durable replies, and task threads. The companion plugin alone does not add this runtime support.

For a new source installation, download and review the installer before running it. It uses Hermes’s supported installer with a fixed source revision. Then run Hermes setup to choose your provider and model.

curl -fL https://raw.githubusercontent.com/RedHillsMediaFL/hermes-agent/fcd35b8307e5b18c7a61d33b43123395b408183a/scripts/install.sh -o hermes-agent-install.sh

HERMES_REPO_URL=https://github.com/RedHillsMediaFL/hermes-agent \
  bash hermes-agent-install.sh --branch agent-companion-v1 \
  --commit fcd35b8307e5b18c7a61d33b43123395b408183a --non-interactive

hermes setup

If Hermes already serves active work, back up its home and finish or safely pause work before an administrator installs this release and restarts it. Choose your existing profile deliberately. Containers, Desktop bundles, and managed images should use their normal deployment process. Agent does not replace a running server’s source or change its provider settings.

2. Configure sign-in and a secure address

In the serving profile’s Hermes configuration, select the basic dashboard authentication provider, choose a username, and set a password hash and a random session signing secret. The basic provider reference documents the supported settings and password-hashing helper. Keep credentials in your protected server configuration rather than command history.

Merge these settings into the serving profile’s configuration, using your own generated values:

dashboard:
  auth_provider: basic
  public_url: https://hermes.example.com
  basic_auth:
    username: your-login-name
    password_hash: YOUR_GENERATED_SCRYPT_HASH
    secret: YOUR_GENERATED_RANDOM_SECRET

Expose the server through HTTPS or your private network. Set dashboard.public_url to the exact HTTPS origin, and trust only the reverse proxies you operate. Keep authentication enabled. Agent supports native username/password sign-in using PKCE; a browser-based OAuth provider is optional.

Start the compatible server in isolated mode for the selected Hermes profile:

hermes serve --isolated --host 127.0.0.1 --port 9119

This binds locally for a reverse proxy or private tunnel. Use your host’s existing service manager to keep it running. A reachable web page alone does not prove Agent compatibility.

3. Connect from Agent

Enter your server address in Agent and sign in. The app checks compatibility and offers to install the companion through Hermes’s authenticated plugin manager. It uses the fixed release below and preserves an existing metadata-preview plugin. It then verifies native capabilities, a WebSocket ping, and the same installation and profile before enabling Connect.

If you prefer to install the companion yourself, run these in the serving profile:

hermes plugins install RedHillsMediaFL/agent-hermes-plugin --ref f954aaa7109aefb070c92559ef546edd85000dcb
hermes plugins enable agent-companion-runtime
hermes plugins doctor agent-companion-runtime --ci

The current plugin is agent-companion-runtime, version 0.2.0. The earlier agent-companion metadata preview can remain installed beside it. Do not force-replace the preview or delete its settings to connect.

Updates and optional features

Keep the reviewed runtime and companion revisions together. Revisit these instructions when updating the beta; pinned installations need an explicit revision change through Hermes’s normal installation tools. Server restarts and source updates remain under the operator’s control.

Features depend on the capabilities your server reports. Life sharing, usage uploads, remote notifications, and other optional integrations are not supplied by the companion plugin. Agent does not require a Red Hills Media account, central relay, or subscription to connect to your own compatible server.