chutes-provider

Hermes Chutes Provider

Standalone Hermes Agent
model-provider plugin for Chutes. Chutes exposes an
OpenAI-compatible API at https://llm.chutes.ai/v1.

This repository intentionally stays outside the Hermes core tree. It uses
Hermes' user model-provider discovery path, so Chutes-specific maintenance does
not need an upstream Hermes source change.

This is an independent, unofficial integration. It is not affiliated with,
endorsed by, sponsored by, or approved by Chutes Global Corp or Nous Research.

Project status

| Area | Current status |
| --- | --- |
| Stable release | v0.1.5 |
| Supported installation | Manual directory install from the released tag |
| Native Hermes install | Pending upstream standalone-plugin support in Hermes PR #64277 |
| Python | 3.11 or newer |
| Distribution | GitHub Releases only; not published to PyPI |

The profile keeps the stable chutes provider identity, discovers current
tool-capable models from the live Chutes catalog, and falls back to Chutes'
routing aliases when that catalog cannot be reached.

Requirements

A Hermes Agent installation with model-provider plugin discovery.
A Chutes API key from chutes.ai/app/api.

Install

Manual directory install

Clone the latest released snapshot into the active Hermes profile:

export HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
mkdir -p "$HERMES_HOME/plugins/model-providers"
git clone --branch v0.1.5 --depth 1 \
  https://github.com/TheStreamCode/hermes-chutes-provider.git \
  "$HERMES_HOME/plugins/model-providers/chutes"

On PowerShell:

$hermesHome = if ($env:HERMES_HOME) { $env:HERMES_HOME } else { Join-Path $HOME ".hermes" }
$target = Join-Path $hermesHome "plugins\model-providers\chutes"
New-Item -ItemType Directory -Force (Split-Path -Parent $target)
git clone --branch v0.1.5 --depth 1 https://github.com/TheStreamCode/hermes-chutes-provider.git $target

Development checkout

To test unreleased changes, clone main instead by omitting --branch and
--depth. Treat that checkout as development code rather than a published
release.

Add the key to $HERMES_HOME/.env:

CHUTES_API_KEY=cpk_...
# Optional endpoint override:
# CHUTES_BASE_URL=https://llm.chutes.ai/v1

| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| CHUTES_API_KEY | yes | none | Bearer credential for inference and catalog requests |
| CHUTES_BASE_URL | no | https://llm.chutes.ai/v1 | Overrides the OpenAI-compatible endpoint |

The key belongs in the Hermes profile's ignored environment file. This
repository never reads it from its own tree and never writes it anywhere.

Then select the provider in $HERMES_HOME/config.yaml:

model:
  provider: chutes
  default: default:latency

Start a new Hermes process and run:

hermes doctor

The Provider Connectivity section should list Chutes. The provider registry
resolves chutes-ai and chutesai as aliases for authentication and runtime
configuration. Use the canonical chutes name in provider:model picker input
and new configuration.

Native Git and pip installs

The eventual native command will be:

hermes plugins install TheStreamCode/hermes-chutes-provider

The package also declares the hermes_agent.model_providers entry point for
pip installation. These routes depend on standalone distribution support from
NousResearch/hermes-agent#64277.
Until that change is merged and included in a Hermes release verified by this
repository, use the manual directory install above.

Models

default:latency is Chutes' routing alias for interactive use. Use
default:throughput for long-running or background work, or select a concrete
model returned by the live
https://llm.chutes.ai/v1/models catalog.

The live catalog is the source of truth for availability, capabilities, and
pricing. The picker keeps the two routing aliases above and includes only live
models that advertise tool calling. This provider intentionally supplies no
static concrete model or auxiliary model, so Hermes does not silently route
requests to retired model IDs. If the catalog is unavailable, the routing
aliases remain selectable; restore network access before choosing a concrete
model instead of relying on a stale local list.

Hermes builds without provider live-metadata support discover model IDs but may
not import their context limits. When selecting a concrete model, copy its live
context_length value to model.context_length in the Hermes configuration.
Routing aliases do not have one fixed context window because their target can
change between requests.

Scope

This plugin declares metadata for Hermes' existing generic OpenAI-compatible
transport and provider-discovery systems. It does not modify Hermes Agent, add
a custom transport, or include Chutes API keys.

flowchart LR
    P["Chutes provider profile"] -->|configures| R["Hermes provider registry"]
    R --> T["Generic OpenAI-compatible transport"]
    T --> C["Chutes API"]

For Chutes skills, setup recipes, model guidance, and platform documentation,
see Veightor/chutes-agent-toolkit.

Repository layout

__init__.py                     directory-plugin entry point (registers on import)
hermes_chutes_provider/         importable package and provider profile
plugin.yaml                     Hermes plugin manifest
pyproject.toml                  packaging metadata and the entry point
tests/test_plugin_profile.py    offline profile, manifest, and docs contract
tests/test_hermes_integration.py opt-in contract against a Hermes checkout
.github/workflows/ci.yml        offline matrix, Hermes integration, wheel build

Development

Run the offline contract tests without a Hermes installation or API key:

python -m unittest discover -s tests -v

The integration test is skipped unless HERMES_SOURCE points at a Hermes
Agent checkout with its dependencies installed:

HERMES_SOURCE=/path/to/hermes-agent python -m unittest discover -s tests -v

Build the wheel the same way CI does:

python -m pip wheel . --no-deps

No test may call paid inference or use a real API key. CI pins the Hermes
revision it tests against, so a Hermes-side change never silently turns the
integration contract red.

Versioning and releases

The project follows semantic versioning. pyproject.toml, plugin.yaml,
CITATION.cff, hermes_chutes_provider.__version__, CHANGELOG.md, and the
manual-install tag above must carry the same version, while CHANGELOG.md and
CITATION.cff must also share the real release date;
test_release_metadata_is_consistent enforces both.
Published versions are listed under
Releases.

Contributing and support

See CONTRIBUTING.md for the change and validation workflow,
SECURITY.md for private vulnerability reporting, and
CODE_OF_CONDUCT.md for participation expectations.
Bugs and feature requests belong in
Issues.

License

Project-owned code and documentation are licensed under the MIT License.
Third-party names, services, and trademarks remain the property of their respective
owners; see NOTICE.

README from the reviewed commit d1165cd; it updates when the author re-pins.

About