Skip to main content

FAQs

Quick answers to the most common Loom questions. New here? Start with What is Loom, then run Hello Loom.

Supported today vs Planned

Supported today (Alpha 1): local execution via loom run --local (Linux target), using host and Docker providers, caching, secrets, and includes/templates.

Planned: remote runners, runner pools, and broader environments.

Installation and setup​

How do I install Loom and run my first workflow?​

Use the canonical release-install procedure. Choose an immutable release version and its matching reviewed installer revision. Do not fetch the installer from main, omit the version, or pass latest.

The default install adds both loom and loom-mcp to ~/.local/bin.

Then follow Hello Loom for the first workflow, validation, local run, and where artifacts land.

Once set up, the standard invocation is:

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

What are the prerequisites?​

  • Always: a Linux environment for loom run --local and a working Loom install on your PATH (Hello Loom).
  • If your workflow uses image: jobs: Docker installed with the daemon running. See Docker provider.
  • Workflow-specific: any language toolchains, CLIs, or credentials your scripts need. Loom runs them — it doesn't install them unless your workflow does.

Is Linux required?​

Yes. Alpha 1 targets Linux for local execution. On macOS or Windows, run Loom inside a Linux environment. Docker-provider jobs (image: set) still work within that Linux context.

Execution and providers​

Is remote execution supported?​

Not today. Alpha 1 is local-only via loom run --local. See CLI run for canonical behavior.

What providers are supported?​

ProviderWhen usedDocs
HostJobs without image: — runs on your local shellHost provider
DockerJobs with image: — runs inside a containerDocker provider

Provider selection is automatic and per-job. See Providers.

Do I need Docker?​

Only if your workflow uses the Docker provider (jobs with image:). Setup and requirements: Docker provider.

Workflow authoring​

Do workflows support variables?​

Yes — variables are a core concept. See Variables.

Do workflows support secrets?​

Yes. Job-level secrets entries store provider references in workflow YAML. Loom redacts exact matches for resolved values in console/event output, recorded state errors, output-bearing errors, and provider lifecycle messages. Transformed values and raw declared artifacts are outside that protection, so inspect evidence before sharing it.

Implemented providers: env://, keepass://, and op:// (1Password via Go SDK — no op CLI required).

How do I add secrets to a workflow?​

Add a secrets block to a job; default.secrets is invalid. Each entry maps a name to a provider URI. This example checks the injected file without printing the value:

deploy:
  stage: ci
  target: linux
  secrets:
    API_TOKEN:
      ref: env://DEPLOY_API_TOKEN
  script:
    - test -r "$API_TOKEN" && test -s "$API_TOKEN"

By default, file: true — the job receives a file path. Read it with cat "$VAR_NAME".

For the full authoring guide: Workflows → Secrets. For local setup patterns: Pattern: secrets for local development.

What do SECRETS_* error codes mean?​

CodeMeaningFix
SECRETS_REQUIRED_MISSINGA required env var isn't setExport it before running Loom
SECRETS_REF_INVALIDThe ref URI is malformedCheck the scheme (env://, keepass://, op://)
SECRETS_PROVIDER_UNAVAILABLEProvider not available (missing auth/config)Verify provider config and credentials
SECRETS_UNSAFE_DEBUG_TRACECI_DEBUG_TRACE=true + file: false secretsDisable trace or switch to file: true

Full reference with cause matrices: Secrets error codes.

Can I compose reusable workflow templates?​

Yes. Use include to import template files and extends to inherit from hidden (.-prefixed) jobs:

include:
  - local: .loom/templates/common.yml

check:
  extends: .base
  stage: ci
  target: linux
  script:
    - pnpm i --frozen-lockfile

See Pattern: templates and includes and Includes and templates.

Caching​

Does Loom support caching?​

Yes. Cache configuration preserves directories such as package stores and build caches between runs. Loom restores a matching cache before running the script. Your package manager or build tool decides which work it can reuse; Loom still invokes the script.

What does --cache-diff compare?​

Run with --cache-diff to compare a cache-off baseline with a cache-on variant in independent workspaces derived from the same pinned input snapshot:

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

The versioned declared-output/v1 contract compares node presence, status, exit code, and content manifests for declared cache paths and declared artifacts. Equality does not prove undeclared workspace side effects, stdout/stderr, timing, network behavior, or universal determinism.

After collecting complete evidence for both executions, Loom quarantines a participating cache-hit candidate for a divergent node only when exactly one eligible scope/key pair is associated with that node. It records ambiguous candidates without quarantine. This comparison does not establish universal cache safety. See Cache concept → Quarantine.

Troubleshooting​

What should I read first when a run fails?​

Read the recorded state first, then the relevant event messages:

  1. Run loom logs <run_id> --state to identify the failed operation and its IDs.
  2. Read loom logs <run_id> --json for contextual output and diagnostics.
  3. Use MCP loom_read_events with job_id or stream to select an excerpt.

See the Diagnostics ladder and Runtime logs contract.

Where are run artifacts stored?​

Under .loom/.runtime/:

ArtifactPathDocs
State and events.loom/.runtime/runs/<run_id>/{state,events}.jsonlRuntime logs
Declared files.loom/.runtime/artifacts/<run_id>/jobs/<job-id>/Artifacts
Validation receipts.loom/.runtime/receipts/Run evidence and receipts
Cache store.loom/.runtime/cache/Cache concept

How do I find the run_id?​

loom run prints the run directory and both JSONL paths. Its directory name is the run ID. MCP loom_run_local returns run_id and the recorded paths.

What should I share when asking for help?​

Follow What to share: include the command, run ID, relevant job/step/command IDs, state and exit code, and a short reviewed event excerpt. For loom check failures, include the validation receipt when available.

What Loom version should I include in a bug report?​

Include the exact Loom binary you ran, any version string the CLI prints, and the run_id plus relevant state and event excerpts. See What to share.

CLI reference​

Full CLI documentation: CLI overview.

Next steps​