How do I install a standalone application that depends on a runtime such as Node?

[chilversc]

I wanted to install a standalone application using npm (specifically @earendil-works/pi-coding-agent) that depends on Node. I was trying to find an equivalent to other applications such as uv tool install for Python.

Because some of the projects I work on use Node (with .node-version) I do not have a global Node version configured so that I cannot accidentally run the wrong version of Node with the project.

What I was looking for, and feel should be simple, is installing a standalone (isolated) tool/application that relies on an engine such as Python or Node. My hope was that mise could manage the engine versions (similar to uv), so that if I had multiple tools that use the same engine I only need to install that engine once. Because the tool is standalone (isolated) it should not matter what the global or project specific version of Node is. The tool should use the version of Node that the tool is pinned to.

I was after a similar simplicity that you get from applications wrote in go or rust, where I would normally just drop a single binary into ~/.local/bin and not have to worry or care about the runtime.

Before installing pi I first ran:

> mise install node
> mise latest node
26.10.0

Attempts

Attempt 1 (did not pin node version)

> mise use -g --pin '@earendil-works/pi-coding-agent@latest'

Config

[tools]
"npm:@earendil-works/pi-coding-agent" = "0.86.1"

The error with this one is understandable, there's no node version selected.

Attempt 2 (still does not pin node version)

> mise use -g --pin '@earendil-works/pi-coding-agent[node=latest]@latest'

Config

[tools]
"npm:@earendil-works/pi-coding-agent" = { version = "0.86.1", node = "latest" }

This one feels like it should not error. Instead it should just use the latest available (installed) Node version. Though I expected --pin to pin the Node version, not just the tool version.

Attempt 3

> mise use -g --pin "@earendil-works/pi-coding-agent[node=$(mise latest node)]@latest"

Config

[tools]
"npm:@earendil-works/pi-coding-agent" = { version = "0.86.1", node = "26.10.0" }

This one does pin both the tool version and Node version. Even so it still fails to actually run the command, which seems odd since it's pinned to a specific Node version so the global Node version shouldn't matter.

Error

In all the cases when I try and run the application I just get the error:

> pi
mise ERROR No version is set for shim: node
Set a global default version with one of the following:
mise use - g node@26.10.0
mise ERROR Version 2026.9.12 linux-x64 (2026-09-20)
mise ERROR Run with --verbose or MISE_VERBOSE=1 for more information

Summary

Overall trying to install a standalone tool pinned to a specific Node version feels more complex than it should be. While I can set a global Node version that could run into issue if I have different tools that require different version of Node (this is something I encounter more often with Python).

[chilversc]

As a follow up, this does not appear to isolate the tool from the environment.

Set the global node to 18, and try and run pi (pi requires node 22.19.0).

> mise use -g node@18
> node --version
v18.20.0
> pi --version
SyntaxError: The requested module 'node:module' does not provide an export named 'enableCompileCache'

This error shows that pi is trying to use node 18. This is even the case if we have "npm:@earendil-works/pi-coding-agent" = { version = "0.86.1", node = "26.10.0" }.

Now switch into a directory that has a .node-version file.

> cat .node-version
22.21.1
> node --version
v22.21.1
> pi --version
0.86.1

So it seems that this approach does not isolate tools/applications that rely on a runtime such as Node or Python from the surrounding environment.

[jdx]

Short answer: there isn't a uv tool install equivalent here, and it isn't something mise can provide for npm packages.

When npm installs a CLI, the executable it puts on PATH is a script whose shebang is #!/usr/bin/env node — it looks up node on PATH at the moment it runs. That's the package's own contract, not something mise adds. uv tool install can isolate a Python CLI because a venv bakes an absolute interpreter path into the script; npm has no equivalent, so there's nothing for mise to pin without rewriting what the package shipped.

That's also usually the behavior you want. Plenty of npm CLIs are project tooling — a formatter, a linter, a process manager like foreman — and those should run on the project's node, not on a version frozen when the tool was installed.

On your attempts:

• node = "latest" / node = "26.10.0" in the tool's options isn't something mise supports. Unrecognized tool options are silently ignored, which is why it looked like it took effect — that part's on us.
• depends = ["node"] is real, but it only orders installation. It has no effect at runtime.
• --pin pins the version of the tool you name, not its dependencies.

What works today is a small wrapper in ~/.local/bin that names both tools:

#!/bin/sh
exec mise exec node@26 'npm:@earendil-works/pi-coding-agent@0.86.1' -- pi "$@"

That resolves independently of whatever mise.toml or .node-version is in the current directory, so pi always gets node 26 and your projects keep theirs. mise installs either tool on demand if it's missing.

Worth knowing about the tradeoff: the pin applies to everything pi spawns, so inside pi the node on PATH is 26, not your project's version. For a coding agent that shells out to project tooling, that may not be what you want. There's no way to get both from a single node on PATH — that's a property of how node CLIs locate their runtime, not something mise decides.

Setting a global node avoids that, but as you found in your follow-up, a project's .node-version still takes precedence inside that project. Which of the two you want depends on whether the tool is meant to act on the project or to be independent of it.

AI-assisted — Tool: Claude Code; model: anthropic/claude-opus-5; version: 2.1.236.

[chilversc]

Like you say, there's two kinds of tools, ones that you want to be based on the project such as the linting, type checking, etc. but then there are system level tools (installed for the current user) that are independent from the project, such as AI coding agents, argonaut, etc.

Some of the more developed tools have their own install script that installs and fetches their own copy of node (similar to how gcloud installs its own copy of Python) but a lot of the smaller utilities just use npm install -g which doesn't work very well in an environment where you have multiple versions of node.

It would be nice if installing standalone applications for Node and Python was as simple as other languages such as tools wrote in Go or Rust. At the moment I always dread when an application uses Node or Python because I know it's going to be much harder to install correctly compared to just downloading a binary into ~/.local/bin.

Is it worth considering that as an additional feature?

As a main feature directly supported by shims

• Tracking which runtimes versions are in use so that unset doesn't try and remove ones that are still used by standalone tools.
• Listing which tools are standalone, and which are project dependent.
• Having the shim use the defined runtime instead of global/project for standalone tools.
• Would need to decide what happens if a project declares the same tool. I would assume the project takes precedence.

Feature supported by tool stubs

Perhaps this could be added to the tool stubs to track the tool (e.g. npm:@earendil-works/pi-coding-agent) separately from the runtime, and track separate versions for the tool and runtime.

Ideally there would be a simple command such as mise tool install --runtime node@26 npm:@earendil-works/pi-coding-agent that would fetch the package and create the stubs based on the executables contained in that package into a standard directory (such as ~/.local/share/mise/tools/).

Add to documentation

Alternatively if it's not considered a first-class feature then we could include a section in the project documentation on installing and running standalone tools.