# Stacks and providers

A **stack** is what you declare in `klyro.yaml`: one runtime, an optional
memory choice, zero or more interfaces, optional model configuration, and a
renderer. Everything the stack references is a **provider**.

## Providers

A provider is curated knowledge, not a runtime plug-in loaded by your project.
Each provider descriptor records identity, category, capabilities,
configuration metadata, lifecycle status, and upstream documentation
references.

Categories stay distinct rather than collapsing into one generic component:

- **Runtime**: the agent process everything else attaches to (Hermes in v0.1).
- **Memory**: conversation and state persistence (Hermes built-in,
  Mnemosyne).
- **Interface**: how you talk to the agent (Telegram, Hermes WebUI).
- **Model configuration**: which model endpoint the agent uses (OpenRouter).
- **Renderer**: the deployment output format (Docker Compose).

## Capabilities and bindings

A **capability** is a stable semantic feature a provider can supply or
require, such as `agent-runtime`, `hermes-memory-provider`, or
`telegram-gateway`.

A **binding** is the explicit mechanism that connects an integration to a
capability supplied by a runtime. For example, the binding
`telegram-gateway-native` targets Hermes' `agent-runtime` capability, while
`mnemosyne-native` targets `hermes-memory-provider`. Compatibility comes from
capabilities plus bindings, not from a pairwise allowlist of services.

Bindings contribute data, not behavior:

- configuration merged into the resolved stack,
- supporting provider dependencies and logical services,
- environment-variable requirements (secret names only),
- mounts and persistence expectations,
- warnings and validation rules.

## From resolved stack to artifacts

Three internal shapes carry your intent through the pipeline:

| Shape            | Meaning                                                                                                                                          |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ResolvedStack`  | Deployment-neutral result of resolution: providers, bindings, transitive dependencies, normalized configuration, required secret names, warnings |
| `DeploymentPlan` | Renderer-ready plan: logical services, networks, volumes, ports, artifact intents                                                                |
| `ArtifactSet`    | Ordered paths and byte content to preview or write                                                                                               |

The same `ResolvedStack` could be rendered by different renderers; v0.1 ships
Docker Compose. This separation is why generated output can stay
[reproducible](/core-concepts/how-it-works/#determinism-is-a-product-feature)
while remaining ordinary Compose you can read.

## Curated support

The catalog is deliberately small. A provider is supported only when its
binding, configuration, persistence, and test expectations are understood:
"containers start" is not evidence that an integration works. The current
matrix lives under [Providers](/integrations/providers/).