Quick start

From a fresh install to a Node 18 project running a Node 22 tool — the core jrt workflow in six steps.

1. Bootstrap the backend

jrt installs runtimes through its own managed copy of mise. This downloads and checksum-verifies it into JRT_HOME. It is needed once per machine.

shell

jrt backend bootstrap

2. Install runtimes

Install as many versions as you like; they live side by side and never replace each other.

shell

jrt runtime install node@18
jrt runtime install node@22
jrt runtime list node

The same works for python, go, rust, dotnet, java, bun, deno and ruby.

3. Pin a project

jrt pin writes a .jrt.toml at the project root. Commit it — everyone on the team gets the same runtime. jrt exec -- runs any command with the pinned runtime.

shell

cd my-legacy-app
jrt pin node@18          # writes .jrt.toml
jrt current              # shows the pins in effect here
jrt exec -- node -v      # v18.x
jrt exec -- npm install

4. Add a machine tool on its own runtime

Here the project stays on Node 18, but Desktop Commander runs on Node 22. compat set records that Node 22 is known-good for this package, tool add locks latest to an exact version, and why explains the decision.

shell

jrt compat set npm:@wonderwhy-er/desktop-commander --runtime node@22 --versions ">=0.2.0 <0.3.0"
jrt tool add desktop-commander npm:@wonderwhy-er/desktop-commander@latest
jrt why desktop-commander
jrt run desktop-commander

Running jrt run desktop-commander from inside the Node 18 project still uses Node 22. The project pin is never touched.

5. One-off commands

Need a runtime just once, without pinning anything?

shell

jrt x node@22 -- node -v          # run once on a runtime, no pin

6. (Optional) Type commands directly

Shims let you drop the jrt exec -- / jrt run prefix. They are opt-in and jrt never edits your PATH on its own.

shell

jrt shim enable
jrt shim add node npm npx
jrt shim path            # prints the PATH line for your shell

Now node -v prints v18 inside the project, your system Node outside it, and desktop-commander works from anywhere. Details in Transparent shims.