Hermes Apertis Provider

A standalone Hermes Agent model-provider plugin for Apertis AI. Apertis exposes an OpenAI-compatible API at https://api.apertis.ai/v1.

This repository is intentionally separate from Hermes Agent. It is discovered from your Hermes profile and does not require a Hermes source-tree change.

Requirements

• A Hermes Agent installation with model-provider plugin discovery.
• An Apertis API key. Create and manage it in your Apertis account; never commit it to this repository or a Hermes project.

Install

Native Hermes install

Hermes versions with standalone model-provider distribution support can install and manage the Git repository directly:

hermes plugins install apertis-ai/hermes-apertis-provider

The manifest declares kind: model-provider, so Hermes places the checkout at $HERMES_HOME/plugins/model-providers/apertis-provider/, prompts for APERTIS_API_KEY when needed, and makes the profile available to hermes model. Model providers do not use the general plugins.enabled list.

This native route depends on Hermes' hermes_agent.model_providers distribution contract. Until that support is present in your installed Hermes release, use the release-pinned installer below.

The concrete compatibility gate is a Hermes version that exposes providers.MODEL_PROVIDER_ENTRY_POINTS_GROUP with the value hermes_agent.model_providers; upstream support is tracked in NousResearch/hermes-agent#64277. Older Hermes releases do not scan the wheel entry point, so use the pinned Git installer until that change appears in a Hermes release.

Release-pinned Git install

The installer works with older Hermes releases and places the provider in the active Hermes profile. Review the tagged script and run it pinned to v1.1.0:

(
  set -eu
  installer=$(mktemp "${TMPDIR:-/tmp}/hermes-apertis-install.XXXXXX")
  trap 'rm -f "$installer"' 0
  trap 'exit 1' HUP INT TERM
  curl --fail --silent --show-error --location \
    --output "$installer" \
    https://raw.githubusercontent.com/apertis-ai/hermes-apertis-provider/v1.1.0/scripts/install.sh
  less "$installer"
  APERTIS_PLUGIN_REF=v1.1.0 sh "$installer"
)

The subshell stops if the download or review step fails and always removes the temporary file. Set HERMES_HOME before running it to install into a non-default Hermes profile. The default is ~/.hermes. The installer requires Git and Python 3, matching Hermes' own runtime requirements.

After reviewing the tagged script, the equivalent non-interactive one-line install keeps the same fail-fast download and cleanup behavior:

( set -eu; installer=$(mktemp "${TMPDIR:-/tmp}/hermes-apertis-install.XXXXXX"); trap 'rm -f "$installer"' 0; trap 'exit 1' HUP INT TERM; curl --fail --silent --show-error --location --output "$installer" https://raw.githubusercontent.com/apertis-ai/hermes-apertis-provider/v1.1.0/scripts/install.sh; APERTIS_PLUGIN_REF=v1.1.0 sh "$installer"; )

To test the current development snapshot instead, clone main directly:

export HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
mkdir -p "$HERMES_HOME/plugins/model-providers"
git clone https://github.com/apertis-ai/hermes-apertis-provider.git \
  "$HERMES_HOME/plugins/model-providers/apertis"

Python package

On a compatible Hermes version, install the wheel into the same Python environment as Hermes:

python -m pip install hermes-apertis-provider==1.1.0

The package has no runtime dependencies and exposes the zero-argument Apertis registration function through hermes_agent.model_providers. Installing it in an unrelated Python environment will not make it visible to Hermes.

Update

Choose the command matching the installation method; do not layer one method on top of another:

# Native Hermes Git install.
hermes plugins update model-providers/apertis-provider

# Python package install.
python -m pip install --upgrade hermes-apertis-provider==1.1.0

If scripts/install.sh is missing, the provider was installed with the earlier manual-clone instructions. Bootstrap that checkout by fast-forwarding it to main once:

git -C "${HERMES_HOME:-$HOME/.hermes}/plugins/model-providers/apertis" \
  pull --ff-only origin main

Then run the APERTIS_PLUGIN_REF=main update below. The installer intentionally rejects non-fast-forward updates, so never use the pinned command to downgrade a checkout that has already advanced beyond v1.1.0; use a separate checkout if you need to preserve an older release.

Run the installed script with the ref you want to follow:

# Follow the current main branch.
APERTIS_PLUGIN_REF=main \
  sh "${HERMES_HOME:-$HOME/.hermes}/plugins/model-providers/apertis/scripts/install.sh"

# Or remain pinned to the stable release.
APERTIS_PLUGIN_REF=v1.1.0 \
  sh "${HERMES_HOME:-$HOME/.hermes}/plugins/model-providers/apertis/scripts/install.sh"

Version-shaped short refs such as v1.1.0 resolve only to release tags. Other short refs resolve only to branches; fully qualified refs/tags/... and refs/heads/... values are also accepted.

Updates fail closed if the target has local changes, an ignored file would be overwritten by the selected ref, the target is not a Git checkout, it uses a different origin, or it cannot fast-forward. The installer never stashes, resets, or deletes an existing provider checkout.

For Git installations, the final directory must contain __init__.py and plugin.yaml directly. A pip installation is independent of that checkout; roll it back with an explicit package version rather than rewriting a Git installation.

Configure Hermes

Add your key to $HERMES_HOME/.env:

APERTIS_API_KEY=your_apertis_api_key

# Optional: route through a compatible proxy or a different Apertis endpoint.
# APERTIS_BASE_URL=https://api.apertis.ai/v1

Select Apertis in $HERMES_HOME/config.yaml:

model:
  provider: apertis
  default: gpt-5.6-sol

The aliases apertis-ai and apertis-api resolve to the same provider.

Models

Hermes queries Apertis' OpenAI-compatible /v1/models endpoint when possible. That live result is authoritative: the models available to you depend on your API key and subscription plan. The small fallback list in this plugin is only used when live model discovery is unavailable; it is not an entitlement guarantee.

To inspect the models available to your account without exposing your key in shell history, use your Apertis account tooling or an environment variable:

curl --fail-with-body https://api.apertis.ai/v1/models \
  -H "Authorization: Bearer ${APERTIS_API_KEY:?Set APERTIS_API_KEY first}"

Verify

After setting APERTIS_API_KEY, run:

hermes doctor

The Provider Connectivity section should list Apertis. A successful health check calls the account-aware /v1/models endpoint.

Development

The published package has no runtime dependencies. Run the repository's offline metadata and installer tests without a Hermes installation, API key, or network access:

python3 -m unittest discover -s tests -v

Scope

This plugin only declares Apertis provider metadata for Hermes' existing generic transport and discovery system. It is distributed through this repository, GitHub Releases, and PyPI. It does not modify Hermes Agent, add a custom transport or authentication flow, or guarantee model access for any Apertis plan.

License

MIT