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(nameandproperty: connectionString, host, port, database, user, password): Kilby fills in the address of a database of the file.fromService(nameandproperty: 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 ofenvGroups, 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.
| Field | Type | Default | What 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.
| Field | Type | Default | What 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.
| Field | Type | Default | What 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.
| Field | Type | Default | What 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.
| Field | Type | Default | What 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.
| Field | Type | Default | What 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.
| Field | Type | Default | What 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.
| Field | Type | Default | What 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.
| Field | Type | Default | What 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.
| Method | Path | Needs | What it does |
|---|---|---|---|
| POST | /blueprints/plan | deploy | Read a file from a repository (or take raw YAML) and return the plan. Changes nothing. |
| POST | /blueprints | deploy and secrets | Create a blueprint from a plan id and start applying it. |
| GET | /blueprints | view | List the blueprints of the workspace. |
| GET | /blueprints/{id} | view | One blueprint: its resources, status and drift. |
| POST | /blueprints/{id}/sync | deploy and secrets | Read the file again and sync now. |
| POST | /blueprints/{id}/approve | deploy and secrets | Approve the changes a sync is waiting on. |
| GET | /blueprints/{id}/syncs | view | The history of syncs. |