kendor.yaml reference

kendor.yaml sits at the root of a challenge's project and tells the sandbox what to run: one language and version, optional extra languages and databases, and one or more services with their install, dev and test commands. Only version, runtime and services are required. Kendor checks the whole file when you save, and a file with errors is not saved.

Where the file lives and when it applies

The file is kendor.yaml at the workspace root. In an uploaded zip or imported repository, Kendor also accepts the kendor.yml spelling.

In the challenge editor, open Settings and choose Configure runtime…. The Runtime configuration dialog has a Form tab and a Raw YAML tab; saving writes kendor.yaml and restarts the preview. If you edit the file by hand instead, a kendor.yaml changed banner appears, because the sandbox still runs the previous setup until you choose Save & restart.

When you save, Kendor runs the checks listed under Validation rules and also checks that every language and database version is one Kendor offers. Each problem is reported with its path in the file, for example services.web.dev.port.

The copy of kendor.yaml inside a running sandbox is regenerated from the saved configuration each time the sandbox starts, so it always shows what the sandbox is running.

What candidates can change

A candidate can edit kendor.yaml in their own workspace. Only four top-level keys are read from their copy: install, services, preview and routing. Their changes apply when the sandbox restarts, and only if the merged file still passes validation; otherwise your configuration stays in place. runtime, toolchains, databases, sandbox and kendor always come from your file, and so do test commands: any test a candidate writes is dropped, and your test commands are kept on the services you defined.

A complete example

A Node.js API and a Vite frontend, with PostgreSQL and Valkey, plus a Python worker:

# 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: api

Top-level keys

Unknown keys are rejected everywhere in the file except inside kendor.

runtime

A challenge's language is fixed when it's created, but its version isn't: when runtime.type is the challenge's language, runtime.version decides which version the sandbox runs.

toolchains

A list of extra languages, each with its compiler, tools and language server on the PATH beside the main one. Use it for a Go service next to a Node app, or Node for asset builds in a PHP project.

Each language may appear once across runtime and toolchains.

databases

A list of database servers that run inside the sandbox on 127.0.0.1 and start before any install command. See Databases in the sandbox for connection details.

install

Commands that run once at the workspace root, before any service starts. Use it for a single install that covers the whole repository, such as pnpm install in a monorepo.

Databases are already running when these commands start, so a migration step here can reach them.

services

A mapping from service name to service. Names start with a lowercase letter and contain only lowercase letters, digits and hyphens, for example api or web-app. The name kendor-db is reserved. Each service runs in its own process window in the sandbox.

Every service needs at least a dev or a test. A service with only test (and no install) gets no process window: this is how single-file challenges are set up.

When a service restarts, its install is skipped if the dependency files in its workDir (package.json, lockfiles, composer.json, requirements.txt, pyproject.toml, go.mod and similar) haven't changed.

dev

Kendor sets these variables for every dev command, and they override anything in env.vars:

Bind your server to $HOST and $PORT (or 0.0.0.0 and the declared port) so the preview can reach it.

Environment variable references

A value in env.vars must use one of four forms. Anything else fails validation.

Databases also set their own variables, such as DATABASE_URL and REDIS_URL, for every process in the sandbox. You only need databases.<type>.url when your code reads a different name.

preview

preview is required when there is more than one service. With one service, that service is the preview. A project whose services have no dev command has no preview, only a terminal.

routing

A list of routes on the sandbox's preview address. Each request goes to the route with the longest matching path prefix. The full path is passed on, so a service routed at /api receives /api/products, not /products.

With routes declared, the preview shows a short waiting page until every routed service is accepting connections. See Multi-service apps.

sandbox

Lets the sandbox run its own container tools.

Either one gives the sandbox more memory and CPU. The preview can open ports published by docker run -p or Compose, and kubectl port-forward with --address 0.0.0.0. A configuration with containers or kubernetes can't define any test command, so there's nothing to run from the Tests tab; use it for challenges you review by reading the work. The pricing page lists container environments under the Enterprise plan.

version: 1
runtime:
  type: node
  version: "22"
sandbox:
  containers: true
services:
  app:
    install:
      commands:
        - npm ci
    dev:
      command: docker compose up

requests

Example HTTP requests that appear, ready to send, in the editor's Requests tab. Requests are sent from inside the sandbox, so localhost works as it does with curl in the terminal. They never change how the sandbox starts.

An example with a mistake is left out of the tab; the others still show.

kendor

Author-only settings. A candidate can't change them. The block accepts extra keys without error.

The block also holds keys that Kendor's own starter catalog uses to describe its starters: title, entryFile, order, type, difficulty, category, tags, editablePaths and solutionDir. They have no effect on your challenge.

Validation rules

A file is saved only when all of these hold:

• version is 1, and runtime and at least one service are present.
• No unknown keys outside kendor.
• Service names match ^[a-z][a-z0-9-]*$ and none is kendor-db.
• Every service has a dev or a test.
• workDir and databases[].init are relative paths inside the workspace: no leading /, no drive letter, no ...
• No two services use the same dev.port.
• preview.service names an existing service, and preview is present when there are two or more services.
• Every routing[].service names an existing service, and every path starts with /.
• Every env.vars value uses one of the four reference forms; routing.<service>.url names an existing service, databases.<type>.url names a declared database, and vars.<NAME> is assessmentId, challengeId or sessionId.
• Each language appears once across runtime and toolchains, and each database type once.
• name and init appear only on a postgres database, and name follows the naming rule above.
• kendor.gradeService and every entry of kendor.gradeServices name existing services, entries of gradeServices have a test, and the two keys aren't used together.
• With sandbox.containers or sandbox.kubernetes, no service has a test and neither gradeService nor gradeServices is set.
• Every language and database version is one Kendor offers. Versions that are no longer offered for new challenges still pass, so a challenge that uses one keeps saving.