Workflows

Loom workflows are defined in .loom/workflow.yml and describe what to run, in what order, and how to diagnose failures when they happen.

The v1 format supports stages, jobs, variables, local templates, secrets, and caches. Runtime receipts and manifests point to the recorded job, script entry, or system section to inspect when a run fails.

If you're new to Loom, start with Getting Started → Hello Loom first, then come back here for the full syntax and patterns.

If you need runtime defaults such as Docker workspace mount mode or provider alias wiring, see Runtime config. .loom/workflow.yml remains the executable workflow source of truth.

Choose the right surface

Workflow definition, runtime defaults, and env-based overrides live in different places on purpose:

Surface	Use it for
.loom/workflow.yml	Jobs, stages, scripts, variables, cache, and secrets references
.loom/config.yml	Repo-scoped runtime defaults for local execution
~/.config/loom/config.yml	User-scoped runtime defaults on one machine
Environment variables	Secret values and one-off runtime overrides

If you are deciding what the pipeline does, stay in the workflow docs. If you are deciding what local defaults Loom should assume before a run starts, go to Runtime config.

Runtime config is runtime-only. It is not a second workflow language.

Minimal workflow (copy/paste)

A schema-valid "hello workflow" you can paste into .loom/workflow.yml and run locally:

version: v1
stages: [ci]

check:
  stage: ci
  target: linux
  script: ["echo hello from Loom"]

• For the full keyword reference, see Syntax (v1).
• For how to run locally, see CLI loom run.

Diagnose a recorded run

Start with the receipt's logs_dir, open pipeline/manifest.json, then follow the failed-job manifest to the relevant step or system events. These files use a consistent structure; their IDs, timestamps, paths, and output vary between runs. Early setup failures can occur before Loom writes a receipt, so use the CLI error when no receipt is available.

• Follow the Diagnostics ladder for the procedure.
• See Runtime logs contract and Receipts contract for file layouts and fields.

What's supported today

• Workflow file: .loom/workflow.yml (or --workflow <path>).
• Local execution: loom run --local (Linux target only in the current release).
• Jobs:
  • Jobs run on the host shell by default, or in Docker when an image: is set.
  • Jobs support optional setup (before_script), a required main command list (script), and optional finalization (after_script). Command entries retain their order and YAML-decoded scalar content.
  • The local executor can run dependency-ready jobs concurrently, using stage and job-name order when selecting among ready jobs. See needs.
• Secrets: jobs can declare secrets that are resolved at runtime and injected securely. See Secrets.
• Strict schema: workflows are validated via loom check (schema v1).

Platform support

• Linux-only local execution: the local runner supports target: linux. If you're on macOS or Windows, run Loom inside a Linux environment (VM, container, or CI runner).

• Docker is optional: you only need Docker if your workflow uses job image: (see Docker provider).

  • Docker prerequisites (daemon reachable, image pullable): see Docker provider → Prerequisites.

• Provider routing is per job:

  Job configuration	Provider used
  No image:	Host provider
  image: set	Docker provider

What's enforced vs what's planned

Loom has two layers to keep separate:

Layer	What it means	Examples
Enforced (schema validation via loom check)	The workflow is schema v1 compliant: required keys, allowed shapes, naming rules	version, stages, stage, target, before_script, script, after_script, variables, cache, secrets
Schema-accepted, runtime evolving	Keywords are accepted so workflows can be written future-compatible, but may not change execution behavior yet	runner_pool (remote execution), invariant (policy checkpoints)

When in doubt, treat the "What's supported today" section as the behavior you can rely on. Planned sections signal direction, not commitment.

Runtime config boundary

The current layered runtime config surface is consumed only by:

• loom config show
• loom run --local

loom check and loom compile still read workflow inputs rather than layered runtime config.

Planned

• Remote execution (runner pools + leases).
• Expanded step semantics.
• Runner pool capability/constraint enforcement.
• Invariant policy checkpoints with decision capture in receipts/events.

Next steps

• Full keyword reference: Syntax (v1)
• Variables: Workflows → Variables and Concepts → Variables
• Caching: Workflows → Cache and Concepts → Cache
• Secrets: Workflows → Secrets and Concepts → Secrets
• Runtime defaults: Runtime config
• Workflow/runtime boundary: Runtime config vs workflow YAML
• Providers: Host vs Docker
• Real example: Examples → Stage 0
• Predefined variables: CI/CD variables (Loom)