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. State and event records identify the job, step or command 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

Use the run ID printed by loom run:

loom logs <run_id> --state
loom logs <run_id> --tail 30

State records identify failed operations and their IDs; the adjacent events.jsonl contains contextual output and diagnostics. MCP clients use loom_read_run and loom_read_events, with job_id or stream filters for messages. If recording could not start, use the terminal error.

• Follow the Diagnostics ladder.
• See Runtime logs for record fields and Run evidence and receipts for validation receipts.

What's supported today

• Workflow file: .loom/workflow.yml (or --workflow <path>).
• Local execution: loom run --local with Linux or macOS host jobs or Linux Docker jobs.
• 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

• Explicit execution targets: native host jobs use target: linux on Linux or target: darwin on macOS. Jobs with an image or image build use Docker and require target: linux. Windows host execution is not supported.

• 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 recording.

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)