Hello Loom

The fastest path to a first successful run, a first artifact set, and a first failure diagnosis. Budget five minutes.

Install Loom

Install the latest released binaries:

curl -fsSL https://gitlab.com/beepbeepgo/loom-build/loom/-/raw/main/install-loom.sh | bash

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. See the CLI overview for install variants.
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: the run finishes and prints a receipt path.

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.

Three hops from receipt to failure evidence. No scrolling, no grepping.

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​