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 released installer:

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

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. Loom has a first-class secrets model for sensitive values. Secrets store references in workflow YAML (not values), and are automatically redacted in all runtime output.

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 (not to default — that's intentionally disallowed). Each entry maps a name to a provider URI:

deploy:
  stage: ci
  target: linux
  secrets:
    API_TOKEN:
      ref: env://DEPLOY_API_TOKEN
  script:
    - curl -H "Authorization: Bearer $(cat $API_TOKEN)" https://api.example.com/deploy

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 between runs (package stores, build caches). On a cache hit, Loom restores outputs in seconds instead of re-running expensive installs or builds.

How do I verify my cache is correct?​

Run with --cache-diff to compare cached outputs against what the job would produce fresh:

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

If outputs diverge, Loom quarantines the cache entry. 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​