Skip to main content

Runtime config

Set local runtime defaults for loom run --local, create them with loom config init, and inspect them with loom config show without changing .loom/workflow.yml.

Runtime config is runtime-only. It is not a second workflow language, and .loom/workflow.yml remains the executable workflow source of truth.

If you want the authoritative file shape, start with Runtime config syntax reference (v1). Use this page as the overview and decision guide, then use the syntax reference when you need the exact supported keys, nested keys, value shapes, and examples.

Choose the right surface​

Use the surface that matches the decision you are making:

SurfaceUse it when you need to decide...Read by...
.loom/workflow.ymlwhat the pipeline does: jobs, stages, scripts, cache, variables, secretsloom check, loom compile, loom run --local
.loom/config.ymlshared repo-scoped local runtime defaultsloom config show, loom run --local
~/.config/loom/config.ymlpersonal machine defaults that should not live in the repoloom config show, loom run --local
Environment variablesone shell, one process, or secret values that should stay outside config filessupported runtime overlays and provider runtimes

If you are defining pipeline behavior, stay in .loom/workflow.yml. If you are setting defaults that Loom should apply before a local run starts, use runtime config.

What runtime config affects today​

The current runtime config surface is intentionally narrow. Today it is consumed only by:

  • loom config show
  • loom run --local

loom check and loom compile do not read layered runtime config.

Where Loom reads it from​

Loom builds the effective runtime config from up to two files:

LayerPathScope
User config~/.config/loom/config.ymlPer-developer defaults on one machine
Repo config.loom/config.ymlShared defaults for one repository

If a file does not exist, Loom skips that layer.

Use loom config init to create a commented starter file at either standard location:

  • loom config init creates .loom/config.yml in the discovered repo
  • loom config init --user creates ~/.config/loom/config.yml

Supported keys in v1​

The current key set is small on purpose:

KeyWhat it controls
runtime.docker.workspaceMountDefault mount mode for Docker-backed local runs
providers.keepass.aliases.<name>.pathDefault KeePass database path for an alias
providers.keepass.aliases.<name>.passwordEnvEnv var name that points to the KeePass password
providers.keepass.aliases.<name>.keyfileEnvEnv var name that points to the KeePass keyfile path
providers.op.serviceAccountTokenEnvEnv var name that should supply the 1Password service account token

Built-in defaults are also narrow. Today the built-in default includes:

runtime:
  docker:
    workspaceMount: ephemeral_volume

Common tasks​

Bootstrap a starter config file​

Create a repo-scoped starter file in the current repo:

loom config init

Create a user-scoped starter file for machine-local defaults:

loom config init --user

Both commands write a commented template with examples for the supported keys.

Share one repo-wide default​

Put stable team defaults in .loom/config.yml:

runtime:
  docker:
    workspaceMount: bind_mount

That changes the default for local Docker-backed runs in this repo. It does not change workflow structure or what loom check validates.

Keep personal settings out of git​

Put machine-specific defaults in ~/.config/loom/config.yml:

providers:
  keepass:
    aliases:
      team/app:
        path: vaults/team-app.kdbx
        passwordEnv: TEAM_APP_PASSWORD
  op:
    serviceAccountTokenEnv: LOOM_OP_TOKEN

This is the right place for personal alias paths or your preferred token-env name. It is not the place for the token value itself.

Inspect the merged result before you run​

loom config show

To test a one-off mount override without editing any file:

LOOM_DOCKER_WORKSPACE_MOUNT=bind_mount loom config show

What runtime config is not for​

Do not use runtime config for:

  • jobs, stages, scripts, cache rules, or workflow secret declarations
  • changing what loom check validates
  • changing what loom compile reads
  • storing raw secret values in checked-in config files
  • image registry credentials in this v1 docs surface