Hello Loom

Create and run a small workflow, inspect its artifacts, then change one command to practice diagnosing a failure.

Install Loom

Follow the canonical release-install procedure. It pins both an immutable release version and the reviewed installer revision for that release. Do not fetch the installer from main, omit the version, or pass latest.

The default installer downloads both loom and loom-mcp from the canonical GitLab release URLs and installs them into ~/.local/bin.

This guide uses loom. If ~/.local/bin is not already on your PATH, follow the script's printed PATH guidance and then verify your install:

loom version

Prerequisites

Loom CLI: available as loom on your PATH. Use the canonical procedure above to install both released binaries.
Shell: any POSIX-compatible shell (bash, zsh)
Docker: optional for this guide. You only need it later if your workflow uses image:.

1) Create a minimal workflow

Create .loom/workflow.yml in your project root:

version: v1
stages: [ci]

hello-host:
  stage: ci
  target: linux
  script:
    - echo "hello from host"

This guide uses a host-only workflow so you can finish without Docker.

Success check: the file exists at .loom/workflow.yml.

If you want a container-backed variant after this guide, see Docker provider.

2) Validate the workflow

loom check

Expected output: validation succeeds and a receipt is written under .loom/.runtime/receipts/.

loom check passed
receipt: .loom/.runtime/receipts/20260301T202909Z-check-4697.json

If validation fails, loom check prints the failing field path and error message to stderr. Fix the reported issue and re-run. See Syntax v1 → Common validator failures for a quick reference.

Success check: you see loom check passed and a receipt path under .loom/.runtime/receipts/.

3) Inspect the execution plan

loom compile --workflow .loom/workflow.yml

Expected output: Graph IR JSON printed to stdout showing the resolved workflow (includes merged, defaults applied).

{ "schema": "loom.graph-ir.v1", "stages": ["ci"] }

Use loom compile to verify template resolution and default merging before running.

Success check: Graph IR prints to stdout and includes your ci stage.

4) Run locally

loom run --local --workflow .loom/workflow.yml

Loom executes each job, then writes structured artifacts. At the end, it prints a receipt path:

receipt: .loom/.runtime/receipts/loom-run-local-1772050684042246000.json

Success check: Loom prints loom run passed and exits with code 0. The receipt should contain status: "success" and exit_code: 0. A receipt path alone does not mean the run succeeded.

If setup fails before Loom can write a receipt, use the error printed to stderr. See Common failures.

Where artifacts land

Loom writes receipts and structured runtime logs under .loom/.runtime/:

.loom/.runtime/
  receipts/
    <run_id>.json                           ← run handle (start here)
  logs/
    <run_id>/
      pipeline/
        summary.json                        ← pipeline status + exit code
        manifest.json                       ← job pointers
      jobs/
        <job_id>/
          summary.json                      ← job status
          manifest.json                     ← step pointers + failing step path
          user/
            execution/
              script/
                <NN>/
                  summary.json              ← step status
                  events.jsonl              ← structured event stream
          system/
            provider/
              summary.json                  ← provider status
              events.jsonl                  ← provider events

When debugging, follow the pointer chain from manifests — open only the failing events.jsonl stream. See Runtime logs contract for the canonical layout.

5) Diagnose an intentional failure

Change one job's script to fail on purpose:

hello-host:
  stage: ci
  target: linux
  script:
    - false

Run again:

loom run --local --workflow .loom/workflow.yml

Then follow the pointer chain to the failure:

Open pipeline/summary.json to confirm the pipeline failed and capture the exit code.
Open pipeline/manifest.json to find failing_job_id and the pointer to the job manifest.
Open jobs/<job_id>/summary.json for the job-level status.
Open jobs/<job_id>/manifest.json to find failing_step_events_path.
Open jobs/<job_id>/user/execution/script/<NN>/events.jsonl for the exact failure evidence.

The manifests locate the failed script entry. Read its output to work out why the command failed; provider failures instead point to a system section.

For a full walkthrough with real artifact excerpts, see the Diagnostics ladder.

Troubleshooting

Symptom	Cause	Fix
Docker jobs fail in provider system section	Docker not running	Start Docker Desktop / daemon. Verify with `docker info`.
"permission denied" writing to `.loom/.runtime/`	File ownership conflict	Verify write permissions on `.loom/`. If a prior Docker run created root-owned files: `sudo chown -R $(whoami) .loom/`
`loom check` prints schema errors	Invalid workflow YAML	Run `loom check`, fix the reported field path. Cross-check against Syntax v1.
`hello-docker` fails but `hello-host` succeeds	Docker not installed or image not pullable	Install Docker, verify `docker pull alpine:3.20` works, or remove the Docker job.

For more, see Common failures and What to share.

Next steps

Goal	Link
Understand the full execution model	How Loom works
Learn the workflow format	Syntax v1
Practice pointer-chain diagnosis	Diagnostics ladder
Run container-backed jobs	Docker provider
Add caching to your workflow	Cache
Add secrets	Secrets
Browse the full CLI	CLI overview

Hello Loom

Install Loom​

Prerequisites​

1) Create a minimal workflow​

2) Validate the workflow​

3) Inspect the execution plan​

4) Run locally​

Where artifacts land​

5) Diagnose an intentional failure​

Troubleshooting​

Next steps​