# Quickstart

This walkthrough creates a complete agent stack from one `klyro.yaml`: Hermes
as the runtime, Mnemosyne for memory, Telegram and the Hermes WebUI as
interfaces, and OpenRouter for model configuration.

## 1. Declare the stack

Create a directory and write a specification file named `klyro.yaml`. You can
also skip this file entirely and answer prompts instead:
[`klyro create`](/cli/commands/#klyro-create) collects the same selections
interactively.

```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
```

Credentials appear as environment-variable **names**, never values. The
[secrets guide](/configuration/secrets/) explains why.

## 2. Validate

```bash
klyro validate klyro.yaml
```

<TerminalCard title="validate">
  <span class="k-t-prompt">$</span> <span class="k-t-cmd">klyro validate klyro.yaml</span>
  <span class="k-t-ok">✓</span> klyro.dev/v1alpha1 · AgentStack · personal-agent
  <span class="k-t-ok">✓</span> Stack resolved: hermes + mnemosyne · telegram + hermes-webui ·
  openrouter
</TerminalCard>

Validation decodes the document against the schema and resolves providers,
bindings, and capabilities against the curated catalog. It writes nothing.
Unsupported combinations fail here with a stable diagnostic instead of
producing a broken project later.

## 3. Plan

```bash
klyro plan klyro.yaml --out ./personal-agent
```

`plan` previews exactly what generation would do: selected providers, chosen
bindings, supporting services, required environment-variable names, ports,
volumes, and every planned artifact with an action (`create`, `overwrite`, or
`skip`) plus a diff of intended content versus what is on disk. Plan output is
deterministic; repeated runs on identical input are byte-identical.

## 4. Generate

```bash
klyro generate klyro.yaml --out ./personal-agent
```

<TerminalCard title="generate">
  <span class="k-t-prompt">$</span>{" "}
  <span class="k-t-cmd">klyro generate klyro.yaml --out ./personal-agent</span>
  <span class="k-t-ok">✓</span> All destinations inspected before the first write
  <span class="k-t-ok">✓</span> compose.yaml · .env.example · .gitignore · README.md ·
  config/hermes/… · klyro.yaml
</TerminalCard>

The generated directory is an ordinary project:

```text
personal-agent/
├── klyro.yaml        # your validated source, copied verbatim
├── compose.yaml      # structured Compose output
├── .env.example      # variable names and blanks, no secrets
├── .gitignore        # ignores .env
├── README.md         # startup, variables, persistence, regeneration
└── config/
    └── hermes/
```

## 5. Run the stack

The generated project is standard Docker Compose. Klyro does not need to be
installed on the machine that runs it:

```bash
cd personal-agent
cp .env.example .env       # fill in OPENROUTER_API_KEY, TELEGRAM_BOT_TOKEN, ...
docker compose config      # inspect the resolved Compose model
docker compose up -d
docker compose down
```

## Regenerating later

Edit `klyro.yaml` and rerun `klyro generate`. By default generation refuses to
overwrite conflicting files; use `--overwrite-owned` to refresh files carrying
Klyro's managed marker, or `--force` to replace every planned conflict.
Unplanned files are never touched. See [Commands](/cli/commands/) for the full
policy reference.

## Next steps

- [How it works](/core-concepts/how-it-works/): what happens between YAML and
  Compose.
- [klyro.yaml reference](/configuration/klyro-yaml/): every supported field.
- [Providers](/integrations/providers/): the v0.1 support matrix.