Skip to content
Klyro Docs

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

Section titled “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 collects the same selections interactively.

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 explains why.

2. Validate

Section titled “2. Validate”
Terminal window
klyro validate klyro.yaml
$klyro validate klyro.yaml✓ klyro.dev/v1alpha1 · AgentStack · personal-agent
✓ Stack resolved: hermes + mnemosyne · telegram + hermes-webui ·
openrouter

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

Section titled “3. Plan”
Terminal window
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

Section titled “4. Generate”
Terminal window
klyro generate klyro.yaml --out ./personal-agent
$ klyro generate klyro.yaml –out ./personal-agent✓ All destinations inspected before the first write
✓ compose.yaml · .env.example · .gitignore · README.md ·
config/hermes/… · klyro.yaml

The generated directory is an ordinary project:

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

Section titled “5. Run the stack”

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

Terminal window
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

Section titled “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 for the full policy reference.

Next steps

Section titled “Next steps”