# Providers

A provider is curated knowledge in Klyro's catalog, not a runtime plug-in
loaded by your generated project. This page is the v0.1 support matrix and the
extension guide for contributors.

## v0.1 support matrix

| Area                | Provider        | Status                                        | Notes                                                                                                                            |
| ------------------- | --------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Runtime             | Hermes          | <StatusPill variant="ok" label="Supported" /> | Official `nousresearch/hermes-agent:v2026.8.18` image; durable `hermes-data` volume.                                             |
| Memory              | Hermes built-in | <StatusPill variant="ok" label="Supported" /> | Runtime self-binding fallback; used when no explicit memory provider wins.                                                       |
| Memory              | Mnemosyne       | <StatusPill variant="ok" label="Supported" /> | Native Hermes plugin installed into the durable volume; first start needs outbound package access and at least 2 GB free memory. |
| Interface           | Telegram        | <StatusPill variant="ok" label="Supported" /> | Native Hermes channel; keep `TELEGRAM_BOT_TOKEN` private and restrict `TELEGRAM_ALLOWED_USERS` to trusted numeric IDs.           |
| Interface           | Hermes WebUI    | <StatusPill variant="ok" label="Supported" /> | Built-in dashboard plus HTTP API; ports 9119 and 8642 are published by the curated Compose profile.                              |
| Model configuration | OpenRouter      | <StatusPill variant="ok" label="Supported" /> | Configuration-only provider; `OPENROUTER_API_KEY` is referenced by name and no model-provider call is made during validation.    |
| Renderer            | Docker Compose  | <StatusPill variant="ok" label="Supported" /> | Generates ordinary Compose files; no Klyro daemon is required after generation.                                                  |

The matrix is deliberately small. Kubernetes, additional runtimes, additional
model marketplaces, and hosted control-plane integrations are outside v0.1.

:::caution
The WebUI and API are intended for a trusted LAN or VPN. Configure dashboard
credentials and `API_SERVER_KEY` before exposing either published port, and
follow the upstream OAuth guidance before any public exposure.
:::

## What a binding means

A provider descriptor declares identity, category, capabilities,
configuration metadata, lifecycle status, and upstream references. A binding
is the explicit mechanism that connects an integration to a capability
supplied by a runtime; for example, `telegram-gateway-native` targets Hermes'
`agent-runtime`, while `mnemosyne-native` targets `hermes-memory-provider`.
The [core concepts page](/core-concepts/stacks-and-providers/) explains the
vocabulary.

The resolver selects compatible bindings. The deployment profile then supplies
renderer-specific facts such as the image, service name, command, ports, and
mount destinations. The Compose planner turns resolved data into a deployment
plan, and the renderer turns the plan into standard files.

## Adding a provider

Provider additions are product changes, not catalog edits. In brief:

1. Add a catalog entry under `packages/catalog/src/providers/` with a stable
   ID, category, status, capabilities, configuration description, and upstream
   documentation references.
2. Add bindings with explicit target capabilities, configuration,
   dependencies, services, environment requirements (secret names only),
   mounts, warnings, and validation rules as applicable.
3. Document ports, network relationships, persistence, known
   incompatibilities, startup network requirements, and the upstream evidence
   for each supported binding.
4. If the provider materializes a Compose service, pin its deployment facts in
   the curated deployment profile. Provider facts stay out of the resolver;
   CLI presentation stays out of the catalog.
5. Add contract tests plus positive and negative resolution fixtures, planner
   and render assertions, and reviewed golden output. Complete fixtures must
   pass `docker compose config` where Docker is available.

Secret values must never appear in source, fixtures, plans, or generated
artifacts. Package boundaries you will touch are described in the
[architecture overview](/contributing/architecture-overview/).