Runtime config syntax reference (v1)

Loom runtime config files are YAML files with a deliberately narrow, runtime-only schema. Use them to set local runtime defaults that loom config show can inspect and loom run --local can consume without changing .loom/workflow.yml.

• User config path: ~/.config/loom/config.yml
• Repo config path: .loom/config.yml
• Consumed by: loom config show, loom run --local
• Not consumed by: loom check, loom compile

Use loom config init to create a commented starter at .loom/config.yml, or loom config init --user to create the user-scoped file at ~/.config/loom/config.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 a key is not documented on this page, treat it as unsupported in v1. Loom reads config files with known-field decoding, so extra nested keys are not part of the supported surface.

File shape at a glance

All sections are optional. If a file or field is missing, Loom falls back to earlier layers and built-in defaults.

The scaffold from loom config init includes commented examples for the same supported keys shown below.

runtime:
  docker:
    workspaceMount: bind_mount

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

Top-level keys

Key	Type	Purpose
runtime	mapping	Local runtime behavior defaults
providers	mapping	Local provider-specific defaults

runtime

Use runtime for execution defaults that affect how loom run --local starts. Today it supports one nested section: docker.

runtime.docker

runtime.docker is a mapping for Docker-backed local execution defaults.

Supported nested keys:

Key	Type	Purpose
workspaceMount	string	Default workspace mount mode for Docker-backed local runs

runtime.docker.workspaceMount

Use runtime.docker.workspaceMount to choose how Loom makes the repo workspace available inside Docker containers during loom run --local.

Value type: string.

Supported values:

• bind_mount
• ephemeral_volume

Built-in default:

runtime:
  docker:
    workspaceMount: ephemeral_volume

Example:

runtime:
  docker:
    workspaceMount: ephemeral_volume

What matters about this key:

• LOOM_DOCKER_WORKSPACE_MOUNT is the supported env overlay for one-off process-level overrides.
• loom run --local --docker-workspace-mount ... sits above file config and env overlays for the current run only.
• This key affects local runtime setup. It does not change workflow syntax, validation, or compilation.

providers

Use providers for provider defaults that Loom turns into runtime env defaults during local execution. Today it supports two nested sections: keepass and op.

providers.keepass

providers.keepass is a mapping with one supported nested key:

Key	Type	Purpose
aliases	mapping	Per-alias KeePass defaults that map onto LOOM_KEEPASS_DB_*

providers.keepass.aliases

Use providers.keepass.aliases to define named KeePass database defaults.

Value type: mapping from alias name to alias object.

Example:

providers:
  keepass:
    aliases:
      team/app:
        path: vaults/team-app.kdbx
        passwordEnv: TEAM_APP_PASSWORD
        keyfileEnv: TEAM_APP_KEYFILE

Each alias object supports these nested keys:

Key	Type	Purpose
path	string	KeePass database path
passwordEnv	string	Env var name that contains the KeePass password
keyfileEnv	string	Env var name that contains the KeePass keyfile path

providers.keepass.aliases.<name>.path

Use path for the database path Loom should use by default for that alias.

Value type: string path.

Example:

providers:
  keepass:
    aliases:
      team/app:
        path: vaults/team-app.kdbx

Path resolution rules:

• Relative paths in ~/.config/loom/config.yml resolve relative to ~/.config/loom.
• Relative paths in .loom/config.yml resolve relative to .loom.
• Paths coming from LOOM_KEEPASS_DB_<ALIAS>_PATH are used as provided.

providers.keepass.aliases.<name>.passwordEnv

Use passwordEnv to store the env var name that should provide the KeePass password at runtime.

Value type: string env var name.

Example:

providers:
  keepass:
    aliases:
      team/app:
        passwordEnv: TEAM_APP_PASSWORD

This field stores the env var name, not the password value.

providers.keepass.aliases.<name>.keyfileEnv

Use keyfileEnv to store the env var name that should provide the KeePass keyfile path at runtime.

Value type: string env var name.

Example:

providers:
  keepass:
    aliases:
      team/app:
        keyfileEnv: TEAM_APP_KEYFILE

This field stores the env var name, not the keyfile contents.

Alias names and env overlays

Loom keeps the alias name you write in config files, but it normalizes aliases when it maps them into env overlay keys:

• letters are uppercased
• digits are preserved
• non-alphanumeric characters become _

Examples:

• team/app becomes TEAM_APP
• prod.eu becomes PROD_EU
• local-main becomes LOCAL_MAIN

That is why the supported env overlays use this shape:

• LOOM_KEEPASS_DB_<ALIAS>_PATH
• LOOM_KEEPASS_DB_<ALIAS>_PASSWORD_ENV
• LOOM_KEEPASS_DB_<ALIAS>_KEYFILE_ENV

If an alias exists only through env overlays and never appears in a config file, loom config show prints the normalized alias name.

providers.op

providers.op is a mapping with one supported nested key:

Key	Type	Purpose
serviceAccountTokenEnv	string	Env var name Loom should read for the 1Password service account token

providers.op.serviceAccountTokenEnv

Use providers.op.serviceAccountTokenEnv to tell Loom which env var name should hold the 1Password service account token at runtime.

Value type: string env var name.

Example:

providers:
  op:
    serviceAccountTokenEnv: LOOM_OP_TOKEN

What matters about this key:

• It stores the env var name, not the token value.
• loom config show prints the env var name reference, not the secret.
• There is no dedicated LOOM_OP_* overlay layer for this field today.
• During loom run --local, Loom reads the configured env var name and uses its current value only if that env var is set and non-empty.

Merge and precedence

Loom builds the effective runtime config in this order:

Priority	Source
1	Built-in defaults
2	~/.config/loom/config.yml
3	.loom/config.yml
4	Supported runtime env overlays

For loom run --local, one extra Docker mount override sits above those layers:

Priority	Source
1	Built-in default ephemeral_volume
2	~/.config/loom/config.yml
3	.loom/config.yml
4	LOOM_DOCKER_WORKSPACE_MOUNT
5	loom run --local --docker-workspace-mount ...

Merge behavior is field-by-field, not whole-file replacement:

• Later layers replace earlier values only for fields they actually set.
• KeePass aliases merge by alias name, so one layer can set path and a later layer can add passwordEnv or keyfileEnv.
• Empty env values are ignored instead of treated as overrides.

Example:

User config:

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

Repo config:

providers:
  keepass:
    aliases:
      team/app:
        keyfileEnv: TEAM_APP_KEYFILE

Effective result:

providers:
  keepass:
    aliases:
      team/app:
        path: /home/alex/.config/loom/vaults/team-app.kdbx
        passwordEnv: TEAM_APP_PASSWORD
        keyfileEnv: TEAM_APP_KEYFILE

Examples

Minimal repo-scoped runtime config

Use .loom/config.yml when the team wants one repo-wide default:

runtime:
  docker:
    workspaceMount: bind_mount

Personal machine defaults

Use ~/.config/loom/config.yml for local-only settings you do not want to check into git:

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

Test a one-off override without editing files

LOOM_DOCKER_WORKSPACE_MOUNT=bind_mount loom config show

That affects only the current process. It does not write back to either config file.

Non-goals and unsupported ideas

Runtime config v1 is intentionally narrow. It is not for:

• defining jobs, stages, scripts, cache rules, variables, or workflow secrets
• changing what loom check validates
• changing what loom compile reads
• storing raw secret values in config files
• image registry credentials in this v1 docs surface
• extra top-level sections such as workflow, default, or variables
• extra provider blocks or nested keys that are not documented on this page

Read next

• Inspect effective config
• Precedence and merge rules
• Provider defaults and alias wiring
• Runtime config vs workflow YAML