ezkeel.yaml spec v1

Per-application declarative deploy spec read by ezkeel up. Place an ezkeel.yaml at the root of your repo to override or augment what auto-detect found. Every field except name is optional.

Required: the first line MUST be the version stamp # spec: ezkeel/v1. Files without it are rejected.

Example

ezkeel.yaml
# spec: ezkeel/v1
name: my-app
framework: express
build: npm run build
start: node dist/index.js
port: 3000

services:
  db:
    engine: postgres
    version: "16"

env:
  - DATABASE_URL
  - NODE_ENV

resources:
  memory: "512m"
  cpus: "1.0"

Field reference

Field	Type	Default	Description
`name`	string	—	RFC 1123 hostname; `^[a-z0-9]([a-z0-9-]*[a-z0-9])?$`; 1-63 chars. Required.
`framework`	string	auto	Override framework detection. See supported list below.
`build`	string	auto	Build command. On Node-server frameworks (express/fastify/hono), setting `build` switches install from `npm ci --omit=dev` to `npm ci` so dev tools (e.g. TypeScript) are available.
`start`	string	auto	Start command. Plain commands emit exec-form CMD; commands with shell metacharacters or leading env-var assignments (`NODE_ENV=...`) emit shell-form (`sh -c`).
`port`	integer	framework	Container port to reverse-proxy.
`services.<k>.engine`	postgres	—	Backing service. `postgresql`/`pg` are aliases. `mysql`/`mariadb` reserved.
`services.<k>.version`	string	"16"	Engine version.
`runtime`	docker / sysbox	docker	Container runtime. sysbox reserved.
`sandbox`	boolean	false	Reserved.
`env`	string[]	—	Required env-var keys. Resolved from Infisical or platform env.
`resources.memory`	string	—	Container memory cap, e.g. `512m`, `1g`.
`resources.cpus`	string	—	CPU cap, e.g. `1.0`, `0.5`.

Supported frameworks

Auto-detect supports: nextjs, remix, nuxt, astro, vite, express, hono, fastify, fastapi, django, flask, go, rust, rails, static.

Setting framework: in the spec rescues a directory the auto-detector cannot classify, and on a switch (auto-detect found one framework, spec overrides to a different one) the framework's canonical defaults replace the detected ones wholesale.

Resolution priority

When multiple sources can name the app or set resources, the priority is:

App name: --name flag > spec.name > repo URL > directory
Resources: --memory/--cpus flags > spec.resources.*
Build/Start/Port: spec values > framework defaults > auto-detected

JSON Schema

Programmatic validators can fetch ezkeel.schema.json (Draft 2020-12).

Versioning policy

v1 is additive. New optional fields will land without breaking existing files. A breaking change requires a new version (# spec: ezkeel/v2) and a parallel parser; the v1 parser will reject unknown stamps with a clear error.

BYO-cloud

ezkeel server add user@host bootstraps any Linux box reachable over SSH (Debian 12, Ubuntu 22.04+, root or non-root with passwordless sudo, 4 GB RAM, ports 80/443/22). The bootstrap installs Docker, the ezkeel agent, and a minimal Caddy reverse-proxy stack at /opt/ezkeel. Hetzner is opt-in sugar via --hetzner. See CLI Reference.