Kilby DocsLog in

Blueprints reference

One file in your repository describes a stack: services, databases, variables, domains and schedules. Kilby shows what will change, applies it, and keeps it in sync.

Overview

A blueprint is a YAML file, usually kilby.yaml at the root of a repository. It names the services and databases of a stack. Kilby reads it and shows a plan: what it would create, change, leave alone or delete, what each costs at list prices, and anything that looks wrong, before anything happens.

You apply the plan once. After that, every push to the branch that changes the file is planned again. Safe changes (adding a service, changing a size) are applied on their own; deleting anything, or anything that could interrupt traffic or lose data, waits in the dashboard until a person approves it. Every sync is kept in a history with the commit, what was applied and who approved it.

A resource is identified by its kind and name inside the blueprint. Renaming a service in the file deletes the old one and creates a new one, and the plan says so.

Examples

A web service, a worker and a database

The api talks to the worker and the database; Kilby fills in the addresses. The session secret is generated once and never appears in the repository.

version: 1
name: acme-platform
databases:
  - name: main
    plan: starter
    storageGb: 5
envGroups:
  - name: shared
    env:
      - key: LOG_LEVEL
        value: info
services:
  - name: api
    type: web
    repo: .
    rootDir: apps/api
    port: 8080
    healthCheckPath: /healthz
    domains: [api.example.com]
    env:
      - key: DATABASE_URL
        fromDatabase: {name: main, property: connectionString}
      - key: WORKER_URL
        fromService: {name: worker, property: hostport}
      - key: SESSION_SECRET
        generateValue: true
      - key: STRIPE_KEY
        sync: false
      - fromGroup: shared
  - name: worker
    type: private
    repo: .
    rootDir: apps/worker
    port: 9000
    env:
      - key: DATABASE_URL
        fromDatabase: {name: main}
      - fromGroup: shared

A monorepo

Two services built from different folders of the same repository. repo: . means the repository that holds this file.

version: 1
name: acme-monorepo
services:
  - name: web
    type: web
    repo: .
    rootDir: apps/web
    plan: standard
    scaling: {min: 1, max: 3, targetCpuPercent: 70}
  - name: api
    type: web
    repo: .
    rootDir: apps/api
    healthCheckPath: /health

A cron job

A job built from the repository and run on a schedule, in UTC.

version: 1
name: nightly-jobs
services:
  - name: nightly
    type: cron
    repo: .
    schedule: "0 3 * * *"
    startCommand: python jobs/nightly.py
    env:
      - key: REPORT_TOKEN
        sync: false

A Render file, converted

Paste a render.yaml in New, Blueprint, Import from Render and Kilby writes this for you, with a report of what changed and what has no equivalent.

# converted from render.yaml
version: 1
name: my-render-app
databases:
  - name: appdb
    plan: starter
services:
  - name: web
    type: web
    repo: .
    buildCommand: npm ci && npm run build
    startCommand: npm start
    healthCheckPath: /health
    env:
      - key: DATABASE_URL
        fromDatabase: {name: appdb, property: connectionString}

Variables

Each entry of env has a key and exactly one way to get its value:

  • value: a literal. It is stored in your repository, so never put a secret here. Kilby warns when a value looks like one.
  • generateValue: true: a random value Kilby creates once and keeps. It is never in git and never changes on a later sync.
  • sync: false: you enter the value in the dashboard when you apply. It is stored encrypted, exactly like a variable you add by hand, and is never written to the plan, the history, a log or anything Kilby AI sees.
  • fromDatabase (name and property: connectionString, host, port, database, user, password): Kilby fills in the address of a database of the file.
  • fromService (name and property: host, port, hostport, url): the address of a web or private service of the file, inside the workspace.
  • fromGroup: name: every variable of an entry of envGroups, in that position of the list.

Names of build-time variables go in buildEnv. Only their names are in the file: the values are entered in the dashboard.

How a sync works

Plan. Kilby compares the file with the workspace field by field. A resource is created, updated (with every field that changes), left alone, deleted or blocked. A resource is blocked, with the reason, when a plan limit would be passed, when its name is used by something the blueprint does not manage, when its GitHub connection is not linked to the workspace, when it names an image of another workspace, or when the file has an error on it. Databases are created first, then services in the order they depend on each other. A dependency cycle is refused.

Apply. Each resource is applied on its own through the same code the dashboard and API use, so every validation and every workspace limit still applies. A failure of one resource does not undo the others. It is recorded with a plain reason and retried on the next sync.

Approval. Deletions, and changes the plan marks as risky, are not applied by a push. The blueprint page shows “2 changes need your approval” with exactly what they are.

Drift. Resources a blueprint manages show “Managed by blueprint” on their pages. If someone changes a managed setting by hand, the resource shows as drifted, and the next plan lists it. With “Put manual changes back” on, the next sync resets it.

Unlink or delete. Unlinking never deletes anything. Deleting the blueprint also deletes everything it manages, after you type its name.

Every field

This reference is generated from the same definitions the parser uses, so it cannot disagree with what Kilby accepts. Unknown fields are errors, with a “did you mean”.

The file

The top level of a kilby.yaml.

FieldTypeDefaultWhat it does
versionrequired number — Schema version of this file. Always 1.One of: 1.
namerequired text — Name of the blueprint: 3 to 40 lowercase letters, digits and hyphens, starting with a letter. Shown in the dashboard as "Managed by blueprint <name>".For example acme-platform
databases list of database — Managed Postgres databases.
envGroups list of envgroup — Sets of environment variables that several services can include with fromGroup.
services list of service — Web services, private services, background workers and cron jobs.
previews previews — Pull request previews. Accepted so a Render file converts cleanly, but not available yet.

databases

A managed Postgres database. Services reach it inside the workspace and get its address with fromDatabase.

FieldTypeDefaultWhat it does
namerequired text — Name of the database: 3 to 30 lowercase letters, digits and hyphens, starting with a letter. Reached at db-<name>-rw:5432.For example main
project text — The project the database is listed in, written as it is named in the workspace (up to 40 characters, no slash). Kilby creates it when it does not exist. On its own it means that project's Production environment. Projects only organize the workspace: they isolate nothing.For example Checkout app
environment text — The environment of the project the database is listed in, for example Production or Staging. Without project it is an environment of the Default project. Kilby creates it when it does not exist. Environments only organize the workspace; moving a database to another one restarts nothing.For example Staging
version text 17 Postgres major version.One of: 17, 18.
plan text starter Instance type of the database.One of: starter, standard, pro.
storageGb number 1 Disk size in GB. A disk can grow but never shrink.One of: 1, 5, 10, 20.
backups true or false true Daily backups with point-in-time recovery. On unless you set false.
highAvailability true or false false Run a standby of the database on another node and fail over to it automatically. It adds a second instance and a second disk. Not available until the platform offers it.

services

A web service, private service, background worker or cron job. A service is built from a repository (repo) or runs an image (image), never both.

FieldTypeDefaultWhat it does
namerequired text — Name of the service: 3 to 40 lowercase letters, digits and hyphens, starting with a letter. It cannot start with db-.For example api
typerequired text — web is public, private is reachable inside the workspace only, worker runs in the background, cron runs on a schedule.One of: web, private, worker, cron.
project text — The project the service is listed in, written as it is named in the workspace (up to 40 characters, no slash). Kilby creates it when it does not exist. On its own it means that project's Production environment. Projects only organize the workspace: they isolate nothing, and every environment shares its limits, members and network.For example Checkout app
environment text — The environment of the project the service is listed in, for example Production or Staging. Without project it is an environment of the Default project. Kilby creates it when it does not exist. Environments only organize the workspace; moving a service to another one restarts nothing.For example Staging
repo text — Where the code lives: "." is the repository that holds this file, or owner/name of another repository the workspace can reach through a linked GitHub installation. Leave out when you set image.For example .
publicGit text — A PUBLIC repository to build from its public archive, with no GitHub connection: its https address on github.com, gitlab.com or bitbucket.org. Use it instead of repo and image. A public repository has no push webhook, so it is built when you ask (the dashboard, the CLI or a build hook), not on every push. A private repository needs repo and the GitHub connection.For example https://github.com/acme/api
branch text — Branch to build and deploy. Defaults to the branch of the blueprint for ".", and to the default branch of another repository. With publicGit it can also be a tag or a full commit id.
rootDir text — Folder of the repository to build, for a monorepo.For example apps/api
runtime text auto auto lets Kilby detect it. dockerfile builds the Dockerfile. static builds a site and serves the output folder.One of: auto, dockerfile, node, python, go, static.
dockerfilePath text — Path of the Dockerfile, relative to rootDir.
buildCommand text — Overrides the build command Kilby detected.
startCommand text — Overrides the start command (git services) or the image's default command (image services).
outputDir text — Folder with the built files a static site serves, relative to rootDir.For example dist
preDeployCommand text — A command that runs once before every deploy, with the new version and its environment, usually database migrations. It runs with /bin/sh -c, so the image needs a shell. If it fails or runs out of time the deploy fails and the running version is not changed. It may run more than once for the same version (a retry or a redeploy; a rollback does not run it), so it must be safe to repeat. Not for cron jobs.For example python manage.py migrate
preDeployTimeoutSeconds number10 to 1800 600 The most seconds the pre-deploy command may run, counted from the start of its container.
image text — A container image to run instead of building a repository, for example ghcr.io/acme/api:1.4. Images in Kilby's own registry can only come from your workspace.For example ghcr.io/acme/api:1.4
registryCredential text — Name of the registry credentials saved in the workspace, for a private image. The password never goes in this file.
port number1 to 65535 — Port the service listens on. Required for image services; Kilby detects it for repositories.
healthCheckPath text — HTTP path Kilby calls to know the service is up. Without it Kilby only checks that the port accepts connections.For example /healthz
plan text starter Instance type. static serves a static site (type web, built from a repository) from Kilby's free static host, where the platform offers it.One of: @serviceplans.
instances number1 to 10 1 Number of instances. Use either instances or scaling.
scaling scaling — Autoscaling between a minimum and a maximum number of instances. Use either instances or scaling.
autoDeploy true or false true Deploy on every push to the branch. On unless you set false. Image services have no pushes.
renderCompatibility true or false false Render compatibility: Kilby also sets the variables Render sets (RENDER=true, RENDER_EXTERNAL_HOSTNAME, RENDER_GIT_COMMIT and the others it can fill truthfully) with this service's values, for code written for Render. A variable you define yourself always wins. Not for static sites. The Render import turns it on.
schedule text — Cron jobs only: five cron fields in UTC.For example 0 3 * * *
disk disk — A persistent disk. A service with a disk runs exactly one instance. A disk can grow but not shrink or be removed.
domains list of text — Custom domains for a web service. Each one needs DNS records you create.For example api.acme.com
env list of envvar — Environment variables, in order. Later entries win.
buildEnv list of text — Names of variables that are also available while the image is built. Names only: the values are entered in the dashboard.
envGroups list of text — Names of environment groups of the workspace that this service uses, the first one winning when two define the same variable. The service's own env wins over all of them. The groups must exist already (Workspace settings, Environment groups); their values stay in them and never go in this file. This list is the complete list of groups of the service. It is not the same as fromGroup, which copies a group written in this file.For example [shared-keys]

env

One entry of a service's variables. Each entry has a key and exactly one way to get its value, or only fromGroup.

FieldTypeDefaultWhat it does
key text — Name of the variable: letters, digits and underscores, not starting with a digit.For example DATABASE_URL
value text — A literal value. It is stored in your repository: never put a secret here.
fromDatabase reference — A property of a database in this file, filled in by Kilby.
fromService reference — A property of a web or private service in this file, filled in by Kilby.
generateValue true or false — A random value Kilby creates once and keeps. It is never in git.
sync true or false — false means the value is entered in the dashboard and never stored in the repository.
fromGroup text — Include every variable of an env group, in this position of the list. Has no key.

scaling

Autoscaling, as a different way to say how many instances a service runs.

FieldTypeDefaultWhat it does
minrequired number1 to 10 — Fewest instances.
maxrequired number2 to 10 — Most instances. Must be higher than min.
targetCpuPercent number10 to 95 70 Add instances when average CPU is above this percentage.

disk

A persistent disk. A service with a disk runs exactly one instance.

FieldTypeDefaultWhat it does
name text — A label for the disk.
mountPathrequired text — Where the disk appears inside the container.For example /data
sizeGbrequired number1 to 50 — Size in GB.

envGroups

A set of variables written in this file that services copy into their own env with fromGroup. To share variables through real environment groups of the workspace (made in the dashboard, with the API or with kilby env-group), list their names in a service's envGroups instead: the values then stay in the groups and never go in this file.

FieldTypeDefaultWhat it does
namerequired text — Name of the group, as services refer to it with fromGroup.For example shared
env list of envvar — The variables of the group.

fromDatabase

Reads a property of a database in the same file.

FieldTypeDefaultWhat it does
namerequired text — Name of a database in this file.
property text connectionString What to read from the database.One of: connectionString, host, port, database, user, password.

fromService

Reads a property of a web or private service in the same file.

FieldTypeDefaultWhat it does
namerequired text — Name of a web or private service in this file.
property text hostport host is the name other services use inside the workspace, port is the port, hostport joins them with a colon, url is http://host:port.One of: host, port, hostport, url.

Import and export

Import from Render. Paste a render.yaml (or pick it from a repository) in New, Import from Render. Kilby converts services, workers, cron jobs, static sites, Postgres databases, env var groups, and every kind of variable, maps each Render plan to the nearest Kilby instance type and shows the price difference. Anything without an equivalent (Redis, regions, workflows, previews) is listed with what to do instead. The result is a kilby.yaml to commit.

Export. Export writes a kilby.yaml from the services, cron jobs and databases a workspace already has. It contains no secret: every variable becomes a name with sync: false.

Security

  • Applying a blueprint needs the permission to deploy and to change secrets, because it creates paid resources, runs code from a repository and sets variables.
  • Every value goes through the same validators as the dashboard and the API: names, images, commands, ports, domains, schedules. An image in Kilby's own registry must belong to your workspace.
  • A blueprint can only use GitHub connections linked to your workspace, and only repositories they can see.
  • A pull request, from a fork or not, never plans or applies a blueprint. Only a push to the branch of a linked blueprint does, and only if the person who linked it can still deploy.
  • The file is read with limits on size, depth, number of resources and alias expansion. Errors never repeat a value that looks like a secret.

Limits

  • A file is at most 256 KB (Kilby reads at most 64 KB of it from GitHub).
  • At most 25 resources (services and databases together), 100 variables a service, strings up to a few thousand characters.
  • YAML 1.2, UTF-8. Anchors and aliases are accepted up to a small bound; a file that expands to more than that is refused.
  • At most 10 blueprints a workspace during the beta. A workspace's own limits (services, CPU, memory, disk) apply to what a blueprint creates, and the plan shows them before anything happens.

Editor support

A JSON Schema of the file is served at https://onkilby.com/schemas/kilby-blueprint.json. Put this line at the top of kilby.yaml and editors with the YAML language server complete field names, show their documentation and mark mistakes as you type:

# yaml-language-server: $schema=https://onkilby.com/schemas/kilby-blueprint.json

API

With an API key, under https://onkilby.com/api/v1. A key never has more access than its creator.

MethodPathNeedsWhat it does
POST/blueprints/plandeployRead a file from a repository (or take raw YAML) and return the plan. Changes nothing.
POST/blueprintsdeploy and secretsCreate a blueprint from a plan id and start applying it.
GET/blueprintsviewList the blueprints of the workspace.
GET/blueprints/{id}viewOne blueprint: its resources, status and drift.
POST/blueprints/{id}/syncdeploy and secretsRead the file again and sync now.
POST/blueprints/{id}/approvedeploy and secretsApprove the changes a sync is waiting on.
GET/blueprints/{id}/syncsviewThe history of syncs.