Desktop Node Environment
Edit pageHagiCode Desktop ships with a Desktop-managed Node toolchain. It does not take over the global Node installation on your computer. Its purpose is to give Desktop startup and runtime-related flows a stable and verifiable runtime foundation.
Read this FAQ if you see portable-fixed/toolchain in diagnostics, need to know which node Desktop is using, or wonder why your system Node version does not directly define Desktop runtime behavior.
Why Desktop bundles Node
Section titled “Why Desktop bundles Node”Desktop needs to run the same supporting flows across operating systems, installation channels, and user environments. If it depended only on the user’s existing Node installation, support would have to handle outdated versions, missing npm, incorrect path ordering, polluted global packages, and organization-specific registry policies all at once.
Desktop describes this more specifically as an isolated Node/npm runtime for managed CLIs instead of reusing the system-wide environment. This design has these main benefits:
- Consistent versions: Desktop uses a pinned Node 22 runtime contract instead of guessing the user’s local major version.
- Controlled startup flows: Desktop-managed commands can prefer the packaged
nodeandnpmentries. - Clear configuration boundaries: CLI-related configuration is kept separate from host-wide global configuration, so updates, switching, and recovery are less likely to be disrupted by system environment differences.
- Reduced conflicts: Bundled paths apply to command environments created by Desktop and do not replace the user’s global Node in their terminal.
- Non-intrusive host behavior: This isolation avoids writing toolchain state into the user’s existing Node/npm environment, and uninstalling Desktop does not disturb the Node, npm, or configuration already present on the machine.
How Desktop selects the Node path
Section titled “How Desktop selects the Node path”When you run Desktop normally, Desktop prefers the Node toolchain installed with the app instead of first reading the Node installation from your system. This keeps the Node version in your terminal separate from the Node version Desktop expects while it runs.
When the bundled toolchain is enabled, command environments created by Desktop put bundled toolchain paths at the front of PATH. As a result, even if your system has another Node version installed, Desktop-managed flows resolve to Desktop’s bundled Node and npm first.
This only affects runtime environments created by Desktop. If you run node, npm, or other commands directly in your system terminal, they continue to use your normal system environment and shell configuration.
In diagnostics or child-process environments started by Desktop, you may see a variable like this:
HAGICODE_PORTABLE_TOOLCHAIN_ROOT=/path/to/portable-fixed/toolchainThis variable means the Desktop-managed runtime environment recognized the bundled toolchain root. Seeing this path does not mean Desktop changed your system Node; it only means Desktop is using the Node environment shipped with the app inside its own runtime scope.
Where Desktop installs managed npm packages
Section titled “Where Desktop installs managed npm packages”Desktop keeps runtime files and mutable npm package files in different locations. The bundled toolchain path such as portable-fixed/toolchain/node is the immutable source for the Desktop-managed node and npm commands. Managed global packages are installed under the Electron user data directory instead:
userData/node22/npmGlobalIf Desktop later moves to Node 24, it uses a separate package tree such as userData/node24/npmGlobal. Packages installed for Node 22 remain on disk but are not treated as installed for Node 24 until they are reinstalled into the new Node-major prefix.
Desktop dependency status only checks the active userData/node<major>/npmGlobal prefix. Package files outside that prefix are ignored by dependency management.