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. 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 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, receipt stdout/stderr, 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?​

Use pointer-first diagnostics. Start with the Diagnostics ladder, then follow artifacts in order:

  1. Receipt — high-level metadata and run pointers: Receipts
  2. Manifest — what happened and where to find details: Runtime logs
  3. Structured events — the smallest "why it failed" evidence
  4. Only then fall back to raw stdout/stderr logs

For the formal schema: Runtime logs contract.

Where are run artifacts stored?​

Under .loom/.runtime/:

ArtifactPathDocs
Receipts.loom/.runtime/receipts/Receipts
Run logs.loom/.runtime/logs/<run_id>/Runtime logs
Cache store.loom/.runtime/cache/Cache concept

Navigate via the receipt and manifests before opening large logs.

How do I find the run_id?​

Two ways:

  • Console output — loom run prints the run_id and logs location.
  • Receipt filename — under .loom/.runtime/receipts/, the receipt name includes the run_id. See Receipts contract.

What should I share when asking for help?​

Start with What to share. As a rule of thumb:

  1. The command you ran (including flags)
  2. The run_id (from console output or receipt)
  3. The receipt path under .loom/.runtime/receipts/
  4. The failing job/step pointer from the manifest (not a pasted wall of logs)

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 receipt/log pointers. See What to share.

CLI reference​

Full CLI documentation: CLI overview.

Next steps​