How Desktop Uses Your Node Environment

HagiCode Desktop no longer ships Node.js or npm with the app, and no longer bundles any other Node toolchain. The only runtime bundled in the Desktop installer is the .NET runtime needed to run Hagicode Server; wherever Node is needed, it uses the node and npm already installed on your system.

Read this FAQ if you want to know which node Desktop actually uses, where Agent CLIs get installed, what to do when Desktop says it cannot find Node, and what the leftover portable-fixed/toolchain directory is after upgrading from an older version.

Version Requirements

Node.js 24 or higher is required (24 is also the minimum). npm is installed together with Node.js. For installation, see Installing Node.js.

Git also needs to be installed by you; see the Installation Guide.

How Desktop Finds node and npm

Desktop reads the system PATH at startup and looks for node, npm, and git in it. This means:

• The version you see from node --version in a terminal is usually the version Desktop uses.
• Desktop only uses your Node environment; it does not replace or modify it.
• If you install or upgrade Node.js while Desktop is already open, fully quit and restart Desktop so it reads the new PATH.

Version Management Tools and PATH

On macOS and Linux, version management tools such as nvm and fnm usually set PATH only in shell configuration files. Desktop launched from the Dock, the application menu, or a desktop icon does not read those files and may not find node. Launch Desktop from a terminal where node already works, or switch to a system-wide installation.

Where Agent CLIs and Other Managed Packages Are Installed

Desktop’s dependency management page discovers the node and npm on PATH, shows the npm global prefix they resolve to, and installs the CLI packages listed in its catalog into this external global directory.

For each managed CLI, Desktop looks for the executable in the following order:

1. An existing managed path
2. The npm global bin directory (on Windows this includes the .cmd and .ps1 launch scripts)
3. PATH

npm mirror settings apply to install and sync operations. Uninstalling also targets the external global directory and requires confirmation in the interface. You can check the current global directory with this command:

npm prefix -g

If the global directory is in a location that requires administrator privileges, you may see permission errors during installation; see Configuring the npm Global Directory.

What to Do When Node or npm Is Not Found

1. Run node --version and npm --version in a terminal and confirm the version is not lower than 24.
2. If it is not installed or the version is too old, install Node.js outside Desktop first.
3. Fully quit and restart Desktop, then go back to the dependency page and click refresh.

When Desktop says a CLI package must be installed manually, run the command it gives in a terminal outside Desktop, then return to Desktop and refresh once so it detects the package again.

What portable-fixed/toolchain Is After an Upgrade

Earlier Desktop versions bundled a Node toolchain with the app, so diagnostics showed a portable-fixed/toolchain path or the HAGICODE_PORTABLE_TOOLCHAIN_ROOT variable, and managed packages were installed in locations such as node22/npmGlobal under the user data directory.

The current version has removed this bundled toolchain:

• The new version no longer uses these paths, and Desktop only checks your local npm global directory.
• The new version does not read CLIs already installed in the old directories. If the dependency page shows that a CLI is not installed, reinstall it in the new npm global directory.