Node.js Management

Corral manages Node.js installations for you — download versions on demand, pin them per project, and run commands with the right version automatically. No need for nvm, fnm, or any other version manager.

Version Resolution

When starting a project or running a command, Corral resolves the Node.js version in this order:

Priority	Source	Example
1	--node-version flag or CORRAL_NODE_VERSION env var	corral exec --node-version 22 node -v
2	Per-project Corral setting	corral project set my-worker node-version 22
3	.node-version file in the project directory	22.3.0
4	.nvmrc file in the project directory	22
5	App-wide default version	corral settings set default-node-version 22
6	Latest installed version	Whatever’s newest in ~/.corral/node/
7	Auto-install latest LTS	Downloads automatically as a last resort

The first match wins. This means a .node-version file in your project will override the app-wide default, and an explicit flag overrides everything.

Installing Node.js Versions

Install a specific version:

corral node install 22.3.0

Install the latest in a major version:

corral node install 22

Install the latest LTS:

corral node install lts

Corral downloads official binaries from nodejs.org and verifies their SHA256 checksums. Installations are stored in ~/.corral/node/v{version}/.

List installed versions:

corral node list

See what’s available:

# All versions (20 most recent)
corral node available

# LTS versions only
corral node available --lts

Remove a version:

corral node remove 22.3.0

Version Specification

You can specify versions in several formats:

Format	Example	Resolves To
Exact	22.3.0 or v22.3.0	That exact version
Major.minor	22.3	Latest patch of 22.3.x
Major	22	Latest version of 22.x.x
LTS	lts or lts/*	Latest LTS release

Per-Project Versions

Option 1: Corral setting

corral project set my-worker node-version 22

Option 2: .node-version file in your project directory:

22.3.0

Option 3: .nvmrc file in your project directory:

22

Corral respects these files automatically. If you’re already using .node-version or .nvmrc with another version manager, Corral will honor them without any extra configuration.

Setting a Global Default

corral settings set default-node-version 22

This version is used when no project-specific version is configured. Clear it with:

corral settings set default-node-version none

Running Commands

Run any command using the resolved Node.js version for the current directory:

corral exec node -v
corral exec npx vitest

Shorthand commands for npm and npx:

corral npm install
corral npx wrangler deploy

Override the version for a single command:

corral exec --node-version 20 node -v

Or via environment variable:

CORRAL_NODE_VERSION=20 corral exec node -v

Shell Shims

For seamless integration with your terminal workflow, install shell shims that make node, npm, npx, and cpm automatically use Corral:

corral install-shims

This creates lightweight scripts in ~/.corral/bin/ that delegate to corral exec. To add them to your PATH:

corral install-shims --patch-profile

This adds ~/.corral/bin to your PATH in your shell profile (~/.zshrc, ~/.bashrc, etc.). After reloading your shell:

# Uses the Corral-resolved version automatically
node -v
npm install
npx vitest

# cpm is a shorthand for `corral pm` — use any package manager syntax
cpm install
cpm add -D vitest

To remove the shims:

corral uninstall-shims

You can also install and manage shims from the macOS app’s Node.js Manager.

Corporate proxies (custom CA certificates)

If you work behind a corporate TLS-intercepting proxy (common at large companies), HTTPS traffic is re-signed with a private corporate root CA. macOS trusts that CA, so browsers work — but Node.js ships its own bundled certificate list and ignores the macOS keychain, so the Node tooling Corral runs fails with errors like:

SELF_SIGNED_CERT_IN_CHAIN
UNABLE_TO_VERIFY_LEAF_SIGNATURE

This breaks npm install, wrangler dev, dependency updates — anything that fetches over HTTPS.

Corral fixes this automatically. On startup (and on demand) it detects the corporate root CAs your Mac already trusts and:

• points NODE_EXTRA_CA_CERTS at them for every Node process it spawns, and
• trusts them for its own downloads (the Node toolchain, cloudflared, self-update).

It only ever trusts roots the OS already trusts, and it’s a complete no-op on a machine with no corporate CAs — so there’s nothing to configure in the common case. If you already set NODE_EXTRA_CA_CERTS yourself, Corral folds your file in rather than overriding it.

The feature is on by default. You can see how many roots were detected — and turn it off, or re-scan after IT installs a new certificate — under Settings → Network & Security → Corporate proxy support. See macOS App Settings.