Reference

task.yaml

A task's configuration is data, never an executable module. task:create scaffolds it beside the entry file. Nothing here is inferred from your code.

Accepted file names

In resolution order — the first match wins.

task.yaml
task.yml
task.json

YAML comes first, because a config needs comments to say why a timeout is 300. JSON is accepted because it is a subset of YAML.

Top-level keys

Key

Required

Holds

schema_version

yes

Must be 1 — the only accepted value. Anything else is refused, naming the field.

slug

yes

Lowercase letters, digits and interior hyphens only, 1–63 characters.

runtime

yes

One of the four runtime rows below.

entry

Entry file. Omitted ⇒ the runtime's default (index.ts, main.py, …).

execution

The seven axes — cardinality, duration, state, interaction, network, residency, storage_mib.

secrets

Secret names only. Values are set with secret:set and never live in this file.

run

Default payload, preset and timeout_sec for task:run.

build

allowed_hosts the build may fetch from; ship paths copied onto the code drive as-is; system_packages Debian packages the task needs (see below).

An unknown top-level key is refused, naming it — a misspelled block reports as invalid rather than silently applying none of its policy.

Runtimes

One row, one runtime — adding a runtime costs the platform one row, never a protocol change. All four are live.

runtime

Entry file

Dependency manifest

Lockfile

node

index.ts

package.json

package-lock.json

python

main.py

requirements.txt

main.go

go.mod

go.sum

rust

src/main.rs

Cargo.toml

Cargo.lock

Every runtime needs a lockfile. An upload without one is refused, because the build would not be reproducible.

Go and Rust compile to one binary and run on the same task image as Node and Python. A binary that needs a system library the image lacks is caught at deploy, not at run.

System packages

A task that needs a Debian tool (ffmpeg, git, wget) lists it under build.system_packages. The build installs the list once. The task VM then finds the tools on its normal path.

build:
  system_packages: [git, ca-certificates, ffmpeg]

Rule

Detail

Names

Bare Debian names only: lower-case letters, digits, + - ., 2–64 characters. No version, no release, no path. Any other name is refused, naming it. A name is never changed for you: FFmpeg is refused, not read as ffmpeg.

Count

At most 64 distinct names. Order does not matter; duplicates count once.

Source

Debian main only, at the snapshot the platform pins. Every name must install exactly as written, or the build fails and says what to fix: a name Debian does not have gets the closest real names, and a virtual name (for example awk) gets the real package to write (mawk).

What is kept

Only new files under /usr and /etc. Documentation, man pages and translations (/usr/share/doc, man, info, locale) are not installed, and files under /var are dropped. A package that changes a file of the base image or creates a user (for example dbus) is refused, naming the paths.

Dependencies

Hard dependencies are installed; recommended packages are not. A tool that talks HTTPS needs ca-certificates in your list.

AI check

ignitify task:validate <id> --review-packages asks the platform's AI to review the list and to estimate the time it adds to the first build. It only advises: the exit code does not change, and a suggestion is not checked against Debian. Only the package names and the runtime id leave your machine, never your code, your slug or your secrets.

Image move

When the platform moves its base image to a new snapshot, a task with an old packages drive is refused. Run ignitify deployment:delete <id>, then deploy again. A hook of the deleted deployment must be created again.

Licences. System packages come from Debian main (free software). Each build keeps a list of the source packages and versions, and the sources stay on snapshot.debian.org.

A complete example

schema_version: 1
slug: streaming-job
runtime: node

execution:
  cardinality: one
  duration: short
  state: independent
  interaction: continuous
  network:
    type: egress

run:
  payload:
    q: war
  timeout_sec: 15