claude-mods/skills/process-compose-ops/references/schema-reference.md

process-compose.yaml Schema Reference

Comprehensive reference for the YAML schema (version: "0.5"). Annotated with field semantics, defaults, and gotchas.

Top-level

version: "0.5"               # required; current schema version

log_level: info              # debug | info | warn | error  (default: info)
log_length: 1000             # lines retained in TUI's in-memory log buffer
log_no_color: false          # disable ANSI colour in log file
log_timestamps: true         # prepend ISO-8601 timestamp to each line
log_truncate: false          # truncate logs on startup instead of appending

processes:                   # required; map of process-name → spec
  <name>:
    ...                      # see Process Spec below

environment:                 # OPTIONAL global env vars applied to every process
  - "GLOBAL_VAR=value"

Process Spec

Required

command: "string"            # shell command to execute (no shell interpolation
                             # unless explicitly wrapped — see "command quoting"
                             # below)

Recommended

working_dir: "/abs/path"     # cwd; otherwise inherits PC's cwd
environment:                 # array of KEY=value strings
  - "ENV_VAR=value"
  - "PYTHONUNBUFFERED=1"

Lifecycle

availability:
  restart: always            # always | exit_on_failure | on_failure | no
  backoff_seconds: 5         # delay before next restart attempt
  max_restarts: 20           # absolute cap; 0 = unlimited
  exit_on_skipped: false     # treat skipped-by-dep failure as exit
  schedule: "0 2 * * *"      # cron schedule for periodic execution
                             # (mutually exclusive with restart: always)

shutdown:
  signal: 15                 # SIGTERM (default) or 9 for SIGKILL
  timeout_seconds: 30        # SIGKILL escalation deadline
  command: "graceful-cli stop"  # optional pre-stop command

Health checks

readiness_probe:             # marks process "Ready" for depends_on
  http_get:
    host: localhost
    port: 8000
    path: /health            # bare "/" is fine if no health endpoint
    scheme: HTTP             # HTTP (default) or HTTPS
  # OR alternative probe types:
  # exec:
  #   command: "curl -f http://localhost:8000/health"
  # tcp_socket:
  #   host: localhost
  #   port: 8000
  initial_delay_seconds: 5   # wait before first probe
  period_seconds: 10         # interval between probes
  timeout_seconds: 3         # per-probe timeout
  success_threshold: 1       # consecutive successes to mark Ready
  failure_threshold: 3       # consecutive failures to mark Not Ready

liveness_probe:              # restarts process if probe fails
  ...                        # same shape as readiness_probe

Dependencies

depends_on:
  database:
    condition: process_healthy   # wait until database's readiness_probe passes
  migrations:
    condition: process_completed_successfully   # wait for one-shot init

Conditions:

Condition	Wait until...	Use when
process_started	Dependency spawned (PID exists)	Weakest; use only when ordering matters but readiness doesn't
process_healthy	Dependency's readiness_probe passes	Strongest; preferred for runtime services
process_completed	Dependency exited (any code)	One-shot init that may fail
process_completed_successfully	Dependency exited 0	One-shot init that must succeed

Logging

log_location: "logs/myapp.log"   # relative to PC's cwd or absolute path
log_max_size_kb: 0               # rotation threshold; 0 = no rotation
log_max_backups: 0               # rotated files to retain
log_max_age_days: 0              # age-based rotation
log_compress: false              # gzip rotated logs

Identity / grouping

namespace: "backend"         # group processes; --namespace flag filters by it
replicas: 3                  # spawn N independent copies (named myapp@0, @1, @2)
disabled: false              # exclude from `up` without deleting the spec
is_daemon: false             # set true for processes that fork and exit
                             # (e.g. systemd-style daemons)

Visibility

is_foreground: false         # show full output in TUI immediately
is_tty: false                # allocate a PTY (interactive processes)
disable_ansi_colors: false   # strip ANSI from this process's logs

Command Quoting

YAML loves to surprise here. Three reliable patterns:

# Pattern 1 — simple command, no quotes anywhere
command: pythonw manage.py runserver 0.0.0.0:8000

# Pattern 2 — single-quoted (literal, no escapes processed)
command: 'pythonw "C:\Program Files\foo\app.py" --port 8000'

# Pattern 3 — double-quoted (escapes processed, watch the backslashes)
command: "pythonw -m my_module"

# Pattern 4 — wrap the exe path in double quotes inside a single-quoted string
command: '"C:/Program Files/Git/usr/bin/bash.exe" --login script.sh'

Windows PATH env vars must be single-quoted to escape backslashes:

environment:
  # WRONG: double quotes try to interpret \P, \U, etc. as escape codes
  # - "PATH=C:\Program Files\Git\usr\bin;..."

  # RIGHT:
  - 'PATH=C:\Program Files\Git\usr\bin;C:\Users\me\AppData\Local\Programs\Python\Python313'

File Composition

You can split config across files and merge:

process-compose up -f base.yaml -f overrides.yaml -f local.yaml

Later files override earlier ones. Useful pattern: base config in repo + per-machine overrides in gitignored local.yaml.

Validation

process-compose up -f process-compose.yaml --dry-run
# → "Validated N configured processes from M files."

Run before committing. Catches:

• YAML parse errors (escape issues, indentation)
• Missing required fields
• Invalid restart policy values
• Circular depends_on chains

Hot Reload

process-compose -p 8888 project update -f process-compose.yaml

Reloads the config in a running PC instance. Added processes start; removed processes stop; changed processes restart.