Reference

Toolchain pins

Deterministic language/tool versions via .moon/toolchains.* + proto. Optional, high leverage.

Why

• Same tool versions on laptop, CI, teammate machines
• Isolated installs (not “whatever is on PATH”)
• Less “works on my machine” drift

Config home

• Workspace: .moon/toolchains.* (optional file)
• Override: project moon.* toolchains block
• Runtime: proto at ~/.proto (moon downloads/reuses tools there)

Enable vs pin

# Enable blocks (empty = enable without auto-install)
javascript:
  packageManager: 'yarn'
node: {}
yarn: {}

# Pin versions → auto download/install on first related task
node:
  version: '20.0.0'
yarn:
  version: '4.0.0'

• Default without toolchain: tasks use system toolchain (PATH only)
• Empty block enables platform features; version enables managed install
• Or: moon toolchain add <toolchain> (not all languages)

Version shapes

• Full 20.0.0 — preferred, least drift
• Partial 20.0 / ^20 — may reuse local match or fetch latest matching
• Alias latest / stable — discouraged (can change daily)

Share one pin with .prototools

# .moon/toolchains.yml
node:
  versionFromPrototools: 'nodejs'  # default true uses same id

# .prototools
nodejs = "~24"

Good pair with Renovate-style auto-updates of one file.

Escape hatch (CI/Docker)

MOON_TOOLCHAIN_FORCE_GLOBALS=true
MOON_TOOLCHAIN_FORCE_GLOBALS=node,yarn

Use preinstalled PATH binaries instead of proto-managed installs.

Related pipeline knobs

• Per-toolchain installDependencies (default true) — install when lock/manifest changes
• Workspace pipeline can also gate install-deps actions (lesson 3 run loop context)