Process Compose compatibility

Kranz opens a supported process-compose.yaml directly, so you can try it on an existing project without maintaining a second configuration.

cd your-project
kranz                       # finds process-compose.yaml automatically
kranz -f process-compose.yaml

A native kranz.yaml in the same directory takes priority, so adding one later is not a breaking change.

A native composition can include a Process Compose file by exact path, glob, or discovery. It is a terminal leaf in that graph: its processes become services, but it cannot declare Kranz include or overrides. The conventional adjacent process-compose.override.yaml is still merged with the leaf, and a composition-wide --override can patch the final effective service names.

Compatibility is deliberately conservative: a feature is either translated faithfully, ignored with a visible diagnostic, or rejected before anything starts. Kranz never accepts a file by quietly dropping a field that changes what your processes do.

Top level

Field	Support	Notes
version	✅ Translated	Kept as the project version
name	✅ Translated	Project name; defaults to the directory name
environment	✅ Translated	Mapping or NAME=value list
processes	✅ Translated	See below
include, overrides	❌ Rejected	Native composition directives are not valid in a terminal leaf

Process fields

Field	Support	Maps to
command	✅ Translated	command
description	✅ Translated	description
working_dir	✅ Translated	dir
environment	✅ Translated	env
env_file	✅ Translated	env_files
depends_on	✅ Translated	depends_on with conditions
readiness_probe	✅ Translated	healthcheck.readiness
liveness_probe	✅ Translated	healthcheck.liveness
ready_log_line	✅ Translated	ready_log_line
availability	✅ Translated	availability
shutdown	✅ Translated	shutdown
success_exit_codes	✅ Translated	success_exit_codes
disabled, is_disabled	✅ Translated	disabled
is_dotenv_disabled	✅ Translated	Skips the adjacent .env
namespace	⚠️ Approximated	Becomes a tag, unless it is default
log_location	⚠️ Ignored	Reported as a diagnostic; Kranz keeps logs in the interface
replicas	❌ Rejected	Values above 1 are not supported
is_daemon	❌ Rejected	Kranz supervises process groups it starts
is_tty, is_interactive, is_foreground	❌ Rejected	Use a Kranz interactive action instead
schedule	❌ Rejected	Kranz is not a scheduler

A rejected field fails the load with a message naming the process and the field. An ignored field loads successfully and reports a diagnostic in the interface.

Dependency conditions

Both the list form and the mapping form are supported:

processes:
  web:
    depends_on:
      api:
        condition: process_healthy
      seed:
        condition: process_completed_successfully

Condition	Support
process_started	✅ (default for the list form)
process_healthy	✅
process_completed	✅
process_completed_successfully	✅
process_log_ready	✅

Any other condition is rejected by name.

Probes

Probe field	Support	Notes
exec.command	✅	Becomes a command check
http_get	✅	Becomes an http check; its port is also declared
http_get.host	✅	Defaults to 127.0.0.1
http_get.scheme	✅	Defaults to http
http_get.path	✅	Defaults to /
http_get.headers	✅	Passed through
http_get.status_code	✅	Defaults to 200
initial_delay_seconds	✅	→ initial_delay
period_seconds	✅	→ interval, default 10s
timeout_seconds	✅	→ timeout, default 1s
failure_threshold	✅	Default 3
success_threshold	⚠️ Approximated	Values above 1 are accepted as 1, with a diagnostic

Exactly one of exec or http_get is required per probe.

What you gain by converting

Compatibility mode gives you the Kranz interface over your existing file. Moving to a native kranz.yaml additionally gives you:

• actions and before_start prerequisites;
• detached lifecycle for Docker and remote resources;
• runtime port discovery and dynamic probe targets;
• ordered override layering with --override;
• project appearance.

The full-stack example ships the same project in both formats, so you can compare them field by field.