Skip to content

Recipe fields

The file is validated strictly: unknown fields are errors, so typos are caught at init, bake and up.

Field Type Default Meaning
version 1 1 the format version
stack name the folder name the stack’s name: lowercase letters, digits, dashes, up to 40
services map of name → service required at least one
ready list of checks [] when the stack counts as up; the first http check is what the bake waits for
migrate command none run once in the app after the services are up, before seeds
tests list of tests [] what forkstage test and the GitHub App run
resources { cpu, memory } 4, 3Gi the microVM’s size
warm, outside reserved; not active in the hosted service
Field Type Meaning
image string a container image. One of image or build, never both
build path a build context in the repository; the image is built during the bake
dockerfile path the Dockerfile inside the build context, when not ./Dockerfile
source path for image services: the repository path mounted at /app
setup command for image services: run once before command, during the bake (install dependencies)
command command overrides the image’s command
port 1 to 65535 the port the service listens on inside the fork
env map environment variables; ${db.url}, ${db.host}, ${db.port} are filled from other services
data empty or { seed } for data stores: schema only, or rows from a .sql file or a command
depends_on list of names start order
resources { cpu, memory } per service, within the VM

A service with build is “the app” for ready, tests, migrate and the public address: the first built service with a port.

Form Passes when
{ http: "service/path" } the path on the service answers 2xx or 3xx
{ tcp: "service" } the service accepts a connection on its port
{ run: "command", in: "service" } the command exits 0 (in the app unless in)
Field Type Meaning
name name shown in proofs and comments
run command run in the app unless in
in name another service
browser boolean reserved

Inside a fork, Postgres, MySQL and Redis services get fixed credentials: user forkstage, password forkstage, database app. ${db.url} renders accordingly:

Image ${db.url}
postgres, pgvector, timescale postgres://forkstage:forkstage@db:5432/app
mysql, mariadb mysql://forkstage:forkstage@db:3306/app
redis, valkey redis://redis:6379
stack: hello
services:
app:
build: .
port: 3000
ready:
- http: app/health