Referencia de kendor.yaml
Todas las claves que acepta kendor.yaml, desde runtime y services hasta routing, databases y sandbox, con sus tipos, valores por defecto y las reglas que se comprueban al guardar.
kendor.yaml está en la raíz del proyecto de un reto e indica al sandbox qué ejecutar: un lenguaje
y su versión, lenguajes y bases de datos adicionales opcionales, y uno o más servicios con sus
comandos de instalación, desarrollo y tests. Solo version, runtime y services son
obligatorios. Kendor comprueba todo el archivo al guardar, y un archivo con errores no se guarda.
Dónde está el archivo y cuándo se aplica
El archivo es kendor.yaml, en la raíz del workspace. En un zip subido o un repositorio importado,
Kendor también acepta la grafía kendor.yml.
En el editor del reto, abre Configuración y elige Configurar runtime…. El cuadro de
Configuración de runtime tiene una pestaña Formulario y otra YAML sin procesar; al
guardar se escribe kendor.yaml y se reinicia la vista previa. Si en cambio editas el archivo a
mano, aparece un aviso kendor.yaml ha cambiado, porque el sandbox sigue ejecutando la
configuración anterior hasta que eliges Guardar y reiniciar.
Al guardar, Kendor ejecuta las comprobaciones indicadas en Reglas de validación
y también comprueba que cada versión de lenguaje y de base de datos sea una de las que ofrece
Kendor. Cada problema se informa con su ruta en el archivo, por ejemplo services.web.dev.port.
La copia de kendor.yaml dentro de un sandbox en marcha se regenera a partir de la configuración
guardada cada vez que arranca el sandbox, así que siempre muestra lo que el sandbox está
ejecutando.
Consejo. Empieza el archivo con
# yaml-language-server: $schema=https://kendor.dev/config-schema/v1. Los editores que usan el
servidor de lenguaje de YAML ofrecerán entonces autocompletado y errores en línea para todas las
claves de esta página.
Qué pueden cambiar los candidatos
Un candidato puede editar kendor.yaml en su propio workspace. De su copia solo se leen cuatro
claves de nivel superior: install, services, preview y routing. Sus cambios se aplican
cuando se reinicia el sandbox, y solo si el archivo combinado sigue superando la validación; de lo
contrario, tu configuración se mantiene. runtime, toolchains, databases, sandbox y kendor
siempre proceden de tu archivo, y lo mismo ocurre con los comandos de tests: cualquier test que
escriba un candidato se descarta, y tus comandos test se conservan en los servicios que
definiste.
Un ejemplo completo
Una API de Node.js y un frontend de Vite, con PostgreSQL y Valkey, más un worker de Python:
# yaml-language-server: $schema=https://kendor.dev/config-schema/v1
version: 1
runtime:
type: node
version: "22"
packageManager: npm
toolchains:
- type: python
version: "3.12"
databases:
- type: postgres
version: "18"
name: shop
init: db/init
- type: valkey
version: "9"
services:
api:
workDir: api
install:
commands:
- npm ci
dev:
command: node --watch src/server.js
port: 3000
env:
vars:
WEB_URL: routing.web.url
CACHE_URL: databases.valkey.url
LOG_LEVEL: lit:debug
test:
command: node --test
web:
workDir: web
install:
commands:
- npm ci
dev:
command: npm run dev -- --port $PORT
port: 5173
env:
vars:
VITE_API_URL: routing.api.url
publicEnvPrefix: VITE_
worker:
workDir: worker
install:
commands:
- pip install --user -r requirements.txt
dev:
command: python worker.py
preview:
service: web
routing:
- path: /api
service: api
- path: /
service: web
requests:
- name: List products
url: http://localhost:3000/api/products
- name: Create a product
method: POST
url: http://localhost:3000/api/products
headers:
Content-Type: application/json
body: '{"name": "Mug", "price": 12}'
kendor:
gradeService: apiClaves de nivel superior
Las claves desconocidas se rechazan en todo el archivo, salvo dentro de kendor.
| Clave | Tipo | Obligatoria | Descripción |
|---|---|---|---|
version |
número | Sí | El formato del archivo. Debe ser 1. |
runtime |
mapa | Sí | El lenguaje principal y su versión. |
toolchains |
lista | No | Lenguajes adicionales en el mismo sandbox. |
databases |
lista | No | Servidores PostgreSQL, MySQL, MongoDB y Valkey dentro del sandbox. |
install |
mapa | No | Comandos que se ejecutan una vez en la raíz del workspace antes de cualquier servicio. |
services |
mapa | Sí | Los procesos que se instalan, inician y prueban, con su nombre como clave. Al menos uno. |
preview |
mapa | Cuando hay 2 o más servicios | Qué servicio muestra el panel de vista previa. |
routing |
lista | No | Prefijos de ruta de la dirección de la vista previa y el servicio al que va cada uno. |
sandbox |
mapa | No | Docker o Kubernetes dentro del sandbox. |
requests |
lista | No | Peticiones HTTP de ejemplo para la pestaña Peticiones del editor. |
kendor |
mapa | No | Ajustes solo para autores. |
Nota. Escribe las versiones como cadenas entre comillas: version: "3.12", no
version: 3.12. Sin comillas, YAML lee 3.12 como un número y el archivo no supera la
validación. El version: 1 de nivel superior es la excepción; debe ser el número 1.
runtime
| Clave | Tipo | Obligatoria | Por defecto | Descripción |
|---|---|---|---|---|
type |
cadena | Sí | Uno de node, php, python, go, java, rust, cpp. |
|
version |
cadena | Sí | Una versión que Kendor ofrezca para ese lenguaje, como "22" o "1.27". Consulta Lenguajes y versiones. |
|
packageManager |
cadena | No | Sin definir | npm, pnpm, yarn o bun. Se guarda como referencia; lo que realmente instala son tus comandos install. |
El lenguaje de un reto se fija al crearlo, pero su versión no: cuando runtime.type es el lenguaje
del reto, runtime.version decide qué versión ejecuta el sandbox.
toolchains
Una lista de lenguajes adicionales, cada uno con su compilador, sus herramientas y su servidor de
lenguaje en el PATH junto al principal. Úsala para un servicio en Go junto a una aplicación de
Node, o para Node en las compilaciones de recursos de un proyecto PHP.
| Clave | Tipo | Obligatoria | Descripción |
|---|---|---|---|
type |
cadena | Sí | Las mismas opciones que runtime.type. |
version |
cadena | Sí | Una versión que Kendor ofrezca para ese lenguaje. |
Cada lenguaje puede aparecer una sola vez entre runtime y toolchains.
databases
Una lista de servidores de bases de datos que se ejecutan dentro del sandbox en 127.0.0.1 y
arrancan antes de cualquier comando de instalación. Consulta
Bases de datos en el sandbox para ver los datos de conexión.
| Clave | Tipo | Obligatoria | Por defecto | Descripción |
|---|---|---|---|---|
type |
cadena | Sí | postgres, mysql, mongodb o valkey. Cada tipo como máximo una vez, y no postgres y mysql a la vez. |
|
version |
cadena | Sí | "18" para PostgreSQL, "8.4" para MySQL, "8.0" para MongoDB, "9" para Valkey. |
|
name |
cadena | No | app |
PostgreSQL, MySQL y MongoDB. La base de datos que se crea: letras minúsculas, dígitos, guiones bajos y guiones, empezando por una letra o un guion bajo, con un máximo de 63 caracteres, y distinta de postgres, template0, template1, admin, local, config, mysql, information_schema, performance_schema y sys. |
user |
cadena | No | kendor |
PostgreSQL, MySQL y MongoDB. El usuario con el que se conecta la aplicación, cuando el proyecto espera uno propio (postgres://shop:secret@localhost/shop). Letras, dígitos, guiones bajos y guiones, con un máximo de 32. Todas las variables de conexión lo usan. |
password |
cadena | No | Sin definir (MongoDB: kendor) |
PostgreSQL, MySQL y MongoDB. La contraseña de ese usuario, una línea de 128 caracteres como máximo. Kendor rellena user, password y name a partir del .env.example o del docker-compose de un repositorio cuando lo importas. |
init |
cadena | No | Sin definir | PostgreSQL, MySQL y MongoDB. Un archivo de seed, o una carpeta cuyos archivos de seed se ejecutan por orden de nombre, relativa a la raíz del workspace: .sql para PostgreSQL y MySQL, .js para MongoDB. Se ejecuta una vez, después de crear la base de datos. |
install
Comandos que se ejecutan una vez en la raíz del workspace, antes de que arranque cualquier
servicio. Úsalo para una única instalación que cubra todo el repositorio, como pnpm install en un
monorepo.
| Clave | Tipo | Obligatoria | Descripción |
|---|---|---|---|
commands |
lista de cadenas | Sí | Al menos una. Se ejecutan en orden; si una termina con un código distinto de cero, se omiten las siguientes. |
Las bases de datos ya están en marcha cuando empiezan estos comandos. Pon las migraciones en los
comandos migrate de un servicio y no aquí: los comandos de instalación se omiten en un reinicio
cuando no ha cambiado ningún archivo de dependencias, así que los archivos de migración nuevos no
se aplicarían.
services
Un mapa de nombre de servicio a servicio. Los nombres empiezan por una letra minúscula y contienen
solo letras minúsculas, dígitos y guiones, por ejemplo api o web-app. El nombre kendor-db está
reservado. Cada servicio se ejecuta en su propia ventana de proceso dentro del sandbox.
| Clave | Tipo | Obligatoria | Por defecto | Descripción |
|---|---|---|---|---|
workDir |
cadena | No | . |
Carpeta en la que se ejecutan los comandos de instalación, desarrollo y tests del servicio, relativa a la raíz del workspace. Sin / inicial y sin ... |
install |
mapa | No | commands: una lista de al menos un comando, que se ejecutan en orden en workDir después del install de nivel superior. Si uno falla, el comando dev del servicio no arranca. |
|
migrate |
mapa | No | commands: una lista de al menos un comando que pone la base de datos al día, como npx prisma migrate deploy o php artisan migrate --force. Se ejecutan en workDir cada vez que arranca el servicio, después de su instalación y antes de dev, con el entorno del servicio. Si uno falla, el error aparece en el proceso del servicio y dev arranca igualmente. |
|
dev |
mapa | No | El proceso de larga duración. Consulta más abajo. | |
test |
mapa | No | command: el comando que ejecuta la pestaña Tests. timeout: segundos que puede tardar antes de detenerse, de 10 a 1800 (por defecto, 10 minutos). Súbelo para suites grandes, como una base de datos de pruebas que tarda en prepararse. |
|
publicEnvPrefix |
cadena | No | El prefijo de las variables que pueden exponerse con seguridad al código del navegador, como VITE_. Se acepta y se guarda; el sandbox no actúa en consecuencia. |
Cada servicio necesita al menos un dev o un test. Un servicio con solo test (y sin install)
no tiene ventana de proceso: así se configuran los retos de archivo único.
Cuando un servicio se reinicia, se omite su instalación si los archivos de dependencias de su
workDir (package.json, lockfiles, composer.json, requirements.txt, pyproject.toml,
go.mod y similares) no han cambiado.
dev
| Clave | Tipo | Obligatoria | Descripción |
|---|---|---|---|
command |
cadena | Sí | El comando que inicia el servicio, por ejemplo npm run dev -- --port $PORT. |
port |
entero | No | De 1 a 65535. El puerto en el que escucha el servicio. Dos servicios no pueden compartir puerto. |
env.vars |
mapa | No | Variables de entorno para este comando. Los nombres cumplen [A-Za-z_][A-Za-z0-9_]*; los valores son referencias, descritas más abajo. |
Kendor define estas variables para todos los comandos de desarrollo, y tienen prioridad sobre
cualquier cosa de env.vars:
| Variable | Valor |
|---|---|
HOST |
0.0.0.0 |
PORT |
El port del servicio, cuando lo tiene. |
KENDOR_PUBLIC_HOST |
El nombre de host público de la vista previa del sandbox. |
KENDOR_VITE_ORIGIN |
El origen público del servicio: la dirección de la vista previa para el servicio de la vista previa, o la dirección del puerto del propio servicio para cualquier otro servicio con puerto. Lo lee el plugin @kendordev/vite. |
Enlaza tu servidor a $HOST y $PORT (o a 0.0.0.0 y al puerto declarado) para que la vista
previa pueda alcanzarlo. El código del navegador que llama a http://localhost:<port> se envía a
ese puerto del sandbox; consulta localhost en la vista previa.
Referencias de variables de entorno
Un valor de env.vars debe usar una de cuatro formas. Cualquier otra falla la validación.
| Forma | Ejemplo | Se resuelve en |
|---|---|---|
routing.<service>.url |
routing.api.url |
La URL pública de ese servicio: la dirección de la vista previa más la ruta de routing más larga del servicio. Solo la dirección de la vista previa cuando la ruta del servicio es / o no tiene ruta. El servicio debe existir. |
databases.<type>.url |
databases.postgres.url |
La URL de conexión de una base de datos declarada en databases. |
vars.<NAME> |
vars.sessionId |
Un valor que proporciona Kendor: assessmentId, challengeId o sessionId. Otros nombres fallan la validación. |
lit:<text> |
lit:debug |
El texto que sigue a lit:, tal cual. |
Las bases de datos también definen sus propias variables, como DATABASE_URL y REDIS_URL, para
todos los procesos del sandbox. Solo necesitas databases.<type>.url cuando tu código lee otro
nombre.
preview
| Clave | Tipo | Obligatoria | Descripción |
|---|---|---|---|
service |
cadena | Sí, cuando preview está presente |
El servicio cuyo servidor de desarrollo muestra el panel de vista previa. Debe existir. |
preview es obligatorio cuando hay más de un servicio. Con un solo servicio, ese servicio es la
vista previa. Un proyecto cuyos servicios no tienen comando dev no tiene vista previa, solo una
terminal.
routing
Una lista de rutas de la dirección de la vista previa del sandbox. Cada petición va a la ruta con el
prefijo de ruta coincidente más largo. La ruta completa se reenvía, así que un servicio enrutado en
/api recibe /api/products, no /products.
| Clave | Tipo | Obligatoria | Descripción |
|---|---|---|---|
path |
cadena | Sí | Empieza por /. Añade una ruta / como comodín. |
service |
cadena | Sí | Un servicio existente. Las rutas a un servicio sin dev.port se omiten. |
Con rutas declaradas, la vista previa muestra una breve página de espera hasta que todos los servicios enrutados acepten conexiones. Consulta Aplicaciones con varios servicios.
sandbox
Permite que el sandbox ejecute sus propias herramientas de contenedores.
| Clave | Tipo | Por defecto | Descripción |
|---|---|---|---|
containers |
booleano | false |
Un demonio de Docker dentro del sandbox, con docker, docker compose y buildx. |
kubernetes |
booleano | false |
Un clúster k3s de un solo nodo que se inicia en el arranque, con kubectl y helm. También activa containers. |
Cualquiera de los dos da más memoria y CPU al sandbox. La vista previa puede abrir los puertos
publicados con docker run -p o Compose, y kubectl port-forward con --address 0.0.0.0. Una
configuración con containers o kubernetes no puede definir ningún comando test, así que no hay
nada que ejecutar desde la pestaña Tests; úsala para retos que revisas leyendo el trabajo. La
página de precios incluye los entornos con contenedores en el plan Enterprise.
version: 1
runtime:
type: node
version: "22"
sandbox:
containers: true
services:
app:
install:
commands:
- npm ci
dev:
command: docker compose uprequests
Peticiones HTTP de ejemplo que aparecen, listas para enviar, en la pestaña Peticiones del
editor. Las peticiones se envían desde dentro del sandbox, así que localhost funciona igual que
con curl en la terminal. Nunca cambian la forma en que arranca el sandbox.
| Clave | Tipo | Obligatoria | Por defecto | Descripción |
|---|---|---|---|---|
name |
cadena | Sí | La etiqueta que se muestra en la lista. | |
method |
cadena | No | GET |
GET, POST, PUT, PATCH, DELETE, HEAD u OPTIONS. |
url |
cadena | Sí | Una URL completa como http://localhost:3000/api/todos, o una ruta como /api/todos, que se envía al puerto del servicio de la vista previa. |
|
headers |
mapa | No | Nombre de cabecera a valor. | |
body |
cadena | No | El cuerpo de la petición. |
Un ejemplo con un error se deja fuera de la pestaña; los demás siguen mostrándose.
kendor
Ajustes solo para autores. Un candidato no puede cambiarlos. El bloque acepta claves adicionales sin error.
| Clave | Tipo | Descripción |
|---|---|---|
gradeService |
cadena | El servicio cuyo test.command ejecuta la pestaña Tests. Por defecto, el servicio de la vista previa. Debe nombrar un servicio existente. |
gradeServices |
lista de cadenas | Varios servicios cuyos comandos de tests ejecuta la pestaña Tests, cada uno en su propio workDir. Los resultados se muestran como service › test. Todos los servicios nombrados deben existir y tener un test. Usa esta clave o gradeService, no ambas. |
El bloque también contiene claves que el catálogo de plantillas de Kendor usa para describir sus
plantillas: title, entryFile, order, type, difficulty, category, tags,
editablePaths, readonlyPaths y solutionDir. No tienen ningún efecto en tu reto: define las
rutas de solo lectura en Configuración del editor de pruebas (consulta
Cómo ejecutan los tests los candidatos).
Reglas de validación
Un archivo se guarda solo cuando se cumple todo lo siguiente:
versiones1, y están presentesruntimey al menos un servicio.- No hay claves desconocidas fuera de
kendor. - Los nombres de servicio cumplen
^[a-z][a-z0-9-]*$y ninguno eskendor-db. - Cada servicio tiene un
devo untest. workDirydatabases[].initson rutas relativas dentro del workspace: sin/inicial, sin letra de unidad y sin...- Dos servicios no usan el mismo
dev.port. preview.servicenombra un servicio existente, ypreviewestá presente cuando hay dos o más servicios.- Cada
routing[].servicenombra un servicio existente, y cadapathempieza por/. - Cada valor de
env.varsusa una de las cuatro formas de referencia;routing.<service>.urlnombra un servicio existente,databases.<type>.urlnombra una base de datos declarada yvars.<NAME>esassessmentId,challengeIdosessionId. - Cada lenguaje aparece una vez entre
runtimeytoolchains, y cada tipo de base de datos una vez. - Como máximo una base de datos SQL:
postgresomysql, no ambas. name,user,passwordeinitaparecen solo en una base de datospostgres,mysqlomongodb, ynamesigue la regla de nomenclatura anterior.kendor.gradeServicey cada entrada dekendor.gradeServicesnombran servicios existentes, las entradas degradeServicestienen untest, y las dos claves no se usan a la vez.- Con
sandbox.containersosandbox.kubernetes, ningún servicio tiene untesty no se define nigradeServicenigradeServices. - Cada versión de lenguaje y de base de datos es una de las que ofrece Kendor. Las versiones que ya no se ofrecen para retos nuevos siguen pasando, de modo que un reto que usa una sigue guardándose.