Declare a Toolchain

TL;DR

Commit `.tool-versions` or `mise.toml` at your repository root to make each Run use the tool versions your project requires. An invalid declared version fails loudly instead of falling back to the Stack image's interpreter.

By default, every Run executes your repo's own build and test commands using the interpreters your Stack's image ships (currently Node 22 and Python 3). If your repo actually builds on a different version — Node 18, an older Python, a language the image doesn't ship at all — this page is how you tell your Stack that, so the agent runs your repo's own toolchain instead.

Which files are read, and how

Drop one of these at your repo root (mise, the version manager your Stack provisions with, walks up from the Workspace root the same way):

• .tool-versions or mise.toml — read for any tool, with no setup required on your side. This is the reliable path: whatever tool and version you name here resolves, whether or not your Stack's image has ever heard of it.

  # .tool-versions
  node 18.20.8
  python 3.12.13

  # mise.toml
  [tools]
  node = "18.20.8"
  python = "3.12.13"

• Idiomatic per-language files (.nvmrc, .node-version, .python-version, and similar) — read only for a pre-seeded set of languages your Stack's image already knows to look for: node, python, ruby, go, java, rust, perl, elixir, crystal, zig, swift, dotnet, deno, bun, terraform, opentofu. A file for one of these resolves the same way .tool-versions does. A language outside this list needs .tool-versions or mise.toml instead — an idiomatic file for it is silently not read.

• package.json's engines field is never read, for any tool. If your repo only pins its Node version there, your Run gets the image's own Node, not an error — engines was never a version-resolution mechanism to begin with, so this isn't a downgrade from anything that used to work.

Declaring nothing at all is a supported, unchanged state: your Run gets exactly the image's own toolchain, the same as before this feature existed.

mise.lock

If your repo already commits a mise.lock (or you add one), your Stack picks it up for free: it adds checksum verification and pinned download URLs for whatever versions it resolves, on top of everything above. There's nothing else to configure for this — it's read automatically whenever present.

If a declared version can't be resolved

A version you actually declared that your Stack can't resolve or install — a typo, a version that no longer exists, a precompiled build unavailable for the Stack's platform — fails the whole Run with an explicit reason, visible in the Run's timeline. Your agent never silently falls back to the image's own interpreter for a version you asked for by name; if that happened, a green Run could quietly be testing the wrong thing.

Related

• Core concepts — the Run/Thread/Event vocabulary this page assumes.