Skip to content

Installation and transport selection

Install Python 3.10–3.14 and create a virtual environment:

python -m venv .venv

Activate the environment in your shell:

source .venv/bin/activate

.venv/Scripts/Activate.ps1

Install a published release from PyPI:

python -m pip install edith-hermes-sdk
python -m pip install "edith-hermes-sdk[control-plane]"  # Local control plane and providers
python -m pip install "edith-hermes-sdk[streaming]"      # Remote WebSocket and event streaming

Extras can be combined: python -m pip install "edith-hermes-sdk[control-plane,streaming]". To pin the release, use edith-hermes-sdk==0.35.0.

Install from source

For development or an unpublished version, get a checkout:

git clone https://github.com/AnasMaar/edith-hermes-sdk.git
cd edith-hermes-sdk

With your environment still active, run from the repository root:

python -m pip install .
python -m pip install ".[control-plane]"  # Local control plane and providers
python -m pip install ".[streaming]"      # Remote WebSocket and event streaming

These commands install your checkout. Extras can be combined: python -m pip install ".[control-plane,streaming]".

Select the endpoint

  • Local orchestration: Hermes.local(runtime=...) starts an in-process control plane with SQLite and a Python tool listener. Provisioning a runtime still requires Docker, a Hermes executable, or an external endpoint, depending on your choice.
  • Remote orchestration: Hermes.remote(base_url, token=...) connects to a running EDITH control plane. The control plane must enable the requested runtime provider. Closing this client does not delete remote instances.
  • Low-level operations: AsyncEdithHermes.remote(base_url=..., token=...) targets the same control-plane HTTP API. AsyncEdithHermes.local() starts an in-process control plane; Docker must be enabled explicitly in its settings. EdithHermes offers synchronous remote/embedded operations.
  • Native gateway: a control-plane profile's connect() provides a persistent WebSocket to the native Hermes gateway. Remote use requires the streaming extra and a compatible gateway/bridge.
  • Desktop REST: AsyncHermesDesktop.remote(base_url=..., profile=..., token=...) targets the Hermes Desktop HTTP server directly, not the EDITH control plane.

Control-plane credentials, provider credentials and connector credentials are separate. Backend capabilities, authentication, runtime images and model availability are deployment-specific. The SDK does not install or authenticate a model for you.

Next: first chat, runtime choices, or existing native sessions.