# klyro.yaml reference

`klyro.yaml` is Klyro's portable source document. It records user intent and
provider references; it never records resolved container topology or live
secret values. `validate`, `plan`, and `generate` all decode the same
document.

## Document envelope

```yaml
apiVersion: klyro.dev/v1alpha1
kind: AgentStack
metadata:
  name: personal-agent
spec:
  runtime:
    provider: hermes
  memory:
    provider: mnemosyne
  interfaces:
    - provider: telegram
    - provider: hermes-webui
  model:
    provider: openrouter
    model: anthropic/example-model
    credential:
      environment: OPENROUTER_API_KEY
  deployment:
    renderer: compose
```

Required top-level fields: `apiVersion`, `kind`, `metadata.name`, and `spec`.
The current API version is `klyro.dev/v1alpha1`; the document kind is
`AgentStack`.

## Supported fields

| Field                               | Meaning                                   | v0.1 values                                   |
| ----------------------------------- | ----------------------------------------- | --------------------------------------------- |
| `spec.runtime.provider`             | Agent runtime                             | `hermes`                                      |
| `spec.memory.provider`              | Memory implementation                     | `builtin` (or omitted), `mnemosyne`           |
| `spec.interfaces[].provider`        | Chat or web interface                     | `telegram`, `hermes-webui`                    |
| `spec.model.provider`               | Model configuration provider              | `openrouter`                                  |
| `spec.model.model`                  | Provider-specific model identifier        | Any non-empty model name                      |
| `spec.model.credential.environment` | Environment variable holding a credential | A variable name, such as `OPENROUTER_API_KEY` |
| `spec.deployment.renderer`          | Output renderer                           | `compose`                                     |

Notes:

- Unknown fields and unknown provider references fail validation with a stable
  diagnostic before generation writes anything.
- The whole `model` section can be omitted when no external model
  configuration is desired.
- Omitting `memory` selects the runtime's built-in memory.

## Command path

```bash
klyro validate klyro.yaml
klyro plan klyro.yaml --out ./my-agent
klyro generate klyro.yaml --out ./my-agent
```

The file path can be given positionally or via `--config <path>`; both
`--config path` and `--config=path` are accepted. See
[Commands](/cli/commands/) for flags and exit codes.

## Source ownership

`create` writes a canonical serialization of its decoded selections. When
`generate` reads a source file instead, it preserves that validated source
text exactly in the output directory, including comments and line endings.
The copied `klyro.yaml` remains the exact document you reviewed, which keeps
the project portable even when the original file lives elsewhere. The
canonical source artifact is user-owned: replacing a differing one requires an
explicit overwrite policy (`--force`).

Secret handling has its own page: [Secrets](/configuration/secrets/).