Release notes

See what changed in each release, why it matters, and whether there are install, compatibility, or security notes before you update.

All releases on GitHub

v0.7.0

Oct 6, 2026

The first Authenticode-signed release, and nvx is on npm. pnpm installs inside the Windows sandbox, nvx setup takes seconds, and the pre-install checks cover every package an npm install brings in.

Added

  • fish and cmd.exe are supported shells. nvx env --shell=fish prints a PATH setup, an nvx function that evaluates use and auto, and a hook on every directory change that also runs once at load, as the zsh one does. nvx use prints fish syntax when it is run from fish. install.sh writes ~/.config/fish/conf.d/nvx.fish for fish, where it used to print a manual fish_add_path command. nvx env --shell=cmd prints a set "PATH=..." line that cmd reads with FOR /f "tokens=*" %i IN ('nvx env --shell=cmd') DO %i. cmd.exe cannot evaluate a program's output, so there is no cmd integration and no AutoRun hook. The shims already run each project's pinned version there.
  • NVX_NODE_MIRROR fetches Node.js from a mirror. nodejs.org was hard-coded, so a network that reaches it only through an internal mirror could not install Node.js. The release index, the archives and SHASUMS256.txt all come from the mirror, as with nvm. An existing NVM_NODEJS_ORG_MIRROR or FNM_NODE_DIST_MIRROR is read too. The checksums come from the same place as the archives, so a mirror is trusted as nodejs.org is.
  • A global policy can now be a baseline a project cannot weaken. Setting "enforced": true in ~/.nvx/policy.json means a project's own .nvx-policy.json may make a setting stricter and may not make one looser. A file that tries is refused, by name: which setting, what the baseline says, and what the file asked for. Nothing runs under a policy nvx could not assemble.

Opt-in and read from the global file only, so every policy already written behaves exactly as it did. A project file that sets the key is told it was ignored rather than left to assume otherwise.

  • nvx policy explain prints each setting's effective value and where it came from: a built-in default, the global policy, one of the project files, or an approval recorded for this project. It also names a project file that is not in force, and says which of the two reasons applies, because "I set this and it is not applying" has more than one cause and they look identical from outside.
  • nvx policy check, a CI gate with a distinct exit code per failure class rather than the blanket 1 every command used before. A pipeline can now tell a blocked package from a vulnerability from a policy file it could not read. The codes are documented in docs/exit-codes.md and pinned to the code by a test. It never prompts, and it makes no network request unless --online is passed, so it cannot hang a job or fail one because a third party is down. --format json prints the same verdict as data, including what was checked and what was skipped.
  • nvx audit export writes the local record as jsonl, json or csv, filtered by --since (a timestamp, or 7d/2w/12h) and by --event. A line that cannot be parsed is reported and the command exits non-zero, having exported and counted everything that could be read: nvx audit skips a torn line silently because it is printing to a screen, and an export that quietly omits records is worse than none. docs/audit-log.md documents every event, its fields, and which parts of that are a contract and which may change.
  • nvx doctor now tells you when a stray package.json has merged your projects into one sandbox. nvx works out which project a sandbox belongs to by looking upward for the nearest manifest, so one sitting above a set of projects quietly joins them together: something installed in either can then read and write the other. Measured on 2026-09-01 — an install run in a home directory left a manifest behind, and every project underneath it, including nvx's own test fixtures, became a single scope. That was already written up under Known limitations, together with the admission that nothing warned you.

Doctor now names the file, says what it means for you, and counts it as a problem so the command exits non-zero. Only a home directory or the top of a drive is reported, because those are the ones that sweep in projects that have nothing to do with each other; a manifest one level up is an ordinary monorepo and is left alone.

  • Fuzz targets for the egress proxy's two parsers. The SOCKS5 handshake and the HTTP CONNECT request are the only things nvx parses whose bytes come from the contained process rather than from a person, and the proxy that parses them runs in the parent, outside the containment, with real network access. A panic there takes down the supervisor of a running sandbox; a hang holds an install open. Until now they had unit tests for the shapes someone thought to write down and nothing for the rest.

Four targets: the two connection handlers driven over net.Pipe, plus validEgressHost and the proxy credential check. The two that matter assert liveness rather than correctness — a parser refusing malformed input is doing its job — while validEgressHost asserts that anything it accepts is free of control characters, since what it accepts is printed to a terminal and written to the audit log, and the credential check asserts that an accepted header decodes to exactly this session's token.

The fuzz configuration cannot reach the network: the allowlist is empty and prompt_unknown is false, so allowed() refuses before dialVetted is called, and the resolver is stubbed because both handlers resolve the host before consulting the allowlist. Measured 2026-09-11: 25 seconds per target, no panic, no hang, no unauthorized acceptance, and no crasher written.

Changed

  • The release workflow Authenticode-signs nvx.exe, with the Certum certificate netscli uses, before any checksum, attestation or SBOM is made over it. Signing runs in its own job, which holds the Certum credentials and receives only nvx.exe, and has no write access to the release. The workflow can be run by hand to build, sign and verify without publishing anything.
  • A failed contained bun install outside the system drive says why. Bun's package manager cannot run in the Windows sandbox in a project on a drive other than the one Windows is installed on, and printed only error: An internal error occurred (EBADF). Measured with Bun 1.4.2, bun install works on C: and fails on D: and H:. After a failed bun install, add, remove, update, patch or pm in such a project, nvx now adds two lines naming the cause and the two ways out. Those are nvx --no-sandbox bun ..., which runs Bun uncontained, or moving the project to the system drive. Bun's fix is in progress as oven-sh/bun#38365.
  • nvx setup covers every fixed drive. It used to grant only the drives holding Windows, your profile, nvx and the current directory, because each grant was slow on a large drive. Now that a grant is fast, one run covers them all and nobody has to run setup again from each drive. --all-drives is still accepted and changes nothing.
  • nvx is on npm as @fstubner/nvx, published through trusted publishing. npm install -g @fstubner/nvx installs the binary for your platform and runs no install script. Releases now publish to npm with the release workflow's GitHub identity rather than a stored npm token, so each version carries npm provenance and there is no NPM_TOKEN secret to leak or expire.
  • The shims run the version the project pins, with or without the shell integration. In a project whose .nvmrc said 20.11, with 22 as the default, node --version through the shim printed v22.23.3 and a warning. Only a shell with the integration loaded switched, so IDE tasks, git hooks, cron, CI and editors running npm run all got the default. node, npm, npx, pnpm, yarn, corepack, bun and bunx now read .nvmrc, .node-version, .bun-version and package.json the way nvx auto does and run the installed version that matches. A version this shell already has active from nvx use still wins. A pinned version that is not installed still runs the default, and the warning now names the nvx install command that fixes it. Contained runs pick the same version, with the policy's runtime.versions ahead of the file. The search for a version file now stops at your home directory.
  • An npm install that brings in new packages now runs npm twice. The first run only resolves versions, so that each package can be checked before the second run installs it. Measured 2026-10-01 on Windows, five runs each with a 5-dependency project and no lockfile, nvx npm install took 5283 to 5573 ms, and 9950 ms on the first run. Without the resolution step it took 3064 to 3219 ms. npm ci and an npm install whose lockfile matches package.json skip it. Because dependencies are now checked, enforce_ignore_scripts refuses a dependency with install scripts, and a dependency inside the release-age window prompts, where before only the packages you named did.
  • The installers check the download's build attestation when gh is present. install.sh and install.ps1 used to compare the download only with the .sha256 file from the same release, which a replaced release could replace as well. When the GitHub CLI is installed, signed in and 2.49 or newer, they now also run gh attestation verify against fstubner/nvx and stop without changing nvx if it fails. Without a usable gh they print one line saying the check was skipped and the command to run. The checksum check is unchanged. The install guide now shows how to verify a downloaded asset by hand.
  • The README is a short front page, and the reference moved to the docs site. Containment, policy, known limitations and the FAQ are now docs pages, and the full nvx help reference is on the Commands page. The tests that held the README's command list to nvx help now read that page.
  • nvx exits 77 when it refuses to run a command, instead of 1. A global install it will not contain, a package that failed pre-install verification, a sandbox it could not establish — all of these returned 1, which is also what npm returns when an install fails on its own terms. A script or an agent loop saw "exit 1" either way and could not tell nvx saying no (fix: --no-sandbox or npx) from a registry timeout (fix: retry) without parsing English off stderr. The audit log already made this distinction (mode=refused, with a reason); this is the same distinction at the one layer a program reads. 77 is EX_NOPERM in sysexits.h. The command's own exit codes are passed through unchanged.
  • The global-install refusal now says what to do if you are an agent. It leads with "nvx refused", states the consequence plainly — anything installed globally runs uncontained on every future invocation — and names npx and a project-local install as the contained alternatives, and tells an agent not to pass --no-sandbox on its own but to inform the person it works for that the install would run uncontained, and let them decide. -q no longer hides any of that: it asks nvx not to narrate progress, and a refusal has no progress to narrate — nvx -q npm install -g used to print the one-line refusal and drop every actionable part of it. The old message offered only the escape hatch, which nudged an automated caller toward the least-contained option and left the person out of the loop.
  • A test whose setup lost a handle now retries, and skips rather than failing if the host keeps refusing. The same Windows condition that refuses a process also refuses a file write: measured 2026-09-10, a test died at write ...\windows-setup.json: The handle is invalid before a single assertion ran, and the identical commit re-run was clean. This is the third face of one host state, after cleanup (removeAllBestEffort) and reading the staged probe child (stageProbeChild).

Applied at the two measured call sites only, not to the 135 t.Fatal(err) setup sites across 52 Windows test files. A sweep that size would be unreviewable and would make every one of those sites quieter about real defects; machinery earns its place from a failure that happened. A persistent refusal skips with a message saying an assertion was not checked, so a run cannot report success for a probe that never executed.

  • macOS: the sandbox-exec provider's availability check now asks about the same path the launcher uses. It had the path written out a second time, so a test that puts nvx on a machine with no sandbox-exec -- the only way to check that nvx refuses rather than running uncontained -- could not reach the provider gate.
  • The tests that need an AF_UNIX socket skip on a long temporary directory rather than failing. The socket path limit is 104 bytes and includes whatever TMPDIR is; under an agent harness's scratch directory that produced a 151-byte path and turned six tests red for a reason unrelated to the code. The skip names the limit and the path.
  • Removed the pre-AppContainer low-integrity token path (five functions and six constants on Windows, plus their no-op Linux twins). Nothing had called any of it since containment moved to AppContainer security capabilities. Code that compiles and looks like the security model, but is not the security model, is the wrong thing to leave in the file someone opens to find out how containment works. Also removed the two helpers that read permissions out of icacls' printed text, superseded by reading the access mask off the entry.
  • nvx report and the Docker provider's environment. SECURITY.md now records that docker run takes allowed environment values as -e KEY=VALUE, so they are visible in the process list to other processes running as you while the container starts. nvx keeps them out of its own output; the argument list is docker's. The native providers are unaffected.

Fixed

  • On macOS, a contained install can no longer write other apps' temp and cache files. The sandbox let every contained process write /private/tmp, /private/var/tmp, all of /dev and all of /private/var/folders, which holds every app's per-user temp and cache directories. A package could plant files there for uncontained programs to read. It now writes only the project, its own temporary home, where its temp directory already was, and a named list of device files such as /dev/null and /dev/tty.
  • --help works after policy init, policy check, policy explain and audit export. Each printed "Unknown option" and exited 1. They now print the command's help and exit 0, as the other commands do.
  • nvx policy check --format=json prints an empty findings list when nothing failed. It printed null, which a script that loops over the list had to treat as a special case.
  • The help text describes what nvx setup, nvx grants list and nvx auto do. setup grants read and list access, not stat access, on the root of every fixed volume and its Users folder. grants list shows egress hosts recorded by older versions, because approving a host at the prompt now lasts one run and is not stored. auto lists .bun-version and the volta entry in package.json, which it reads, and no longer names a separate Volta file.
  • pnpm installs inside the Windows sandbox. pnpm 10 resolves the project directory with fs.promises.realpath, which asks Windows for the path with its drive letter, and an AppContainer is refused that on every path. A first pnpm install stopped with EPERM: operation not permitted, realpath. The preload nvx puts in every contained node process now retries a refused native realpath with Node's JavaScript one, which walks the path with lstat and readlink and reaches the same answer. Measured 2026-10-04 with pnpm 10.34.6 on Node 22.23.3: a first install now completes in projects on C: and on H:.
  • A second pnpm install in the sandbox works. pnpm keeps its package store in the home folder when the project is on the same drive, and records the store's path in node_modules/.modules.yaml. Every contained run had a new home, so the next install found a different store and stopped with ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY. Contained pnpm commands now share one home per project that is kept between runs, as a trusted tool's is. No other project and no other package manager uses it. Measured 2026-10-05 with pnpm 10.34.6 on Windows: two installs in a row now both finish in a project on C:. A project already installed by an earlier nvx still records the old path, so delete its node_modules folder once.
  • nvx setup no longer spends minutes on each large drive. On 2026-10-04 nvx setup --all-drives granted D:\ in 1 second and E:\ in 3, then was still working on F:\ after 33 minutes. The grant is one entry on the drive root that nothing below the root inherits. Writing it made Windows re-check the permissions of every file on the volume, which changed nothing. Setup and nvx setup --undo now write the root's own permissions and leave the rest of the volume alone. On a test directory holding 20,000 files the old write took 2.67 to 3.01 seconds and the new one under 1 millisecond, and no file's permissions changed either way. The same write used to drop the directory's auto-inherited mark, and now keeps it as it was.
  • The typosquat check no longer refuses dependencies you did not choose. The pre-install checks run over the whole resolved tree, and the typosquat check asked api.npmjs.org for the weekly downloads of every package in it. On 2026-10-04 npm ci over a 415-package tree got HTTP 429 from that API, the lookups fell back to name similarity, and the legitimate transitive package regex was refused as a typosquat. A typosquat is a name someone typed wrongly, and a dependency's name was written by its author. The check now runs only on the packages named on the command line, or with none named, on the dependencies in package.json. The blocklist, release-age, install-script and advisory checks still cover the whole tree. Download lookups are also remembered for the rest of the run.
  • A command that turns install scripts off is no longer asked about them. npm ci --ignore-scripts in a project depending on chromedriver stopped at the install-script prompt, and npm install esbuild --ignore-scripts aborted non-interactively with exit 77, although npm ran none of those scripts. The install-script prompt and the enforce_ignore_scripts refusal are now skipped when --ignore-scripts is on the command line (also --ignore-scripts=true), when npm_config_ignore_scripts=true is in the environment, or when the project .npmrc sets ignore-scripts=true. bun reads only the flag. A run inside the sandbox gets no npm_config_* variables, so the environment does not count there. --ignore-scripts=false does not count. The skip is recorded once per run as check_skipped. The typosquat, release-age, advisory and blocklist checks still run.
  • nvx use in cmd.exe no longer prints bash or PowerShell syntax. Run from a cmd window opened out of Git Bash it printed export PATH='/c/...' lines and told you to add a line to ~/.bashrc, because the MSYSTEM variable Git Bash sets is inherited. In any other cmd window it printed PowerShell syntax. nvx now asks which process started it and finds cmd.exe. It says that cmd cannot be switched by a program, that the shims already follow the project's version file, that nvx default <version> sets the version for new windows, and gives the one command that switches only that window. The same check makes nvx env and nvx doctor use cmd syntax there. A PowerShell, bash, zsh or fish parent is recognised the same way.
  • On Windows, contained runs now work under a long NVX_HOME. The sandbox reaches nvx through sockets that lived under NVX_HOME, and a socket path must stay under 108 bytes. Measured on 2026-10-01, a 132-character NVX_HOME needed a 174-byte path and every run that used the egress proxy refused with exit 77. The longest that worked was 65 characters. Long values are common on Windows, with profiles redirected to OneDrive or corporate home folders. When the sockets do not fit under NVX_HOME, nvx now puts them in the sandbox's own folder in %LOCALAPPDATA%\Packages, which Windows already grants the sandbox. The same run then used a 90-byte path and completed. When that folder's path is too long as well, the refusal names the longest NVX_HOME that works.
  • Packages from a private registry are now checked on that registry. The pre-install checks asked registry.npmjs.org about every package. A package served only by a private registry came back 404, and with nobody to answer the prompt the install was refused. nvx now reads the registry npm will use for each package from .npmrc and npm_config_*, scopes included. A contained install reads the project's .npmrc only, as its npm does. When the registry needs a token to read metadata, nvx sends the _authToken from your .npmrc with its own request. The token does not reach the sandbox or any log. A package from a registry other than registry.npmjs.org skips the typosquat and advisory checks, because both send the name to a public service. The run says so in one line and the audit log records it as check_skipped.
  • Contained installs now work behind a corporate proxy. nvx's egress proxy dialled every allowed host itself, and the contained process got nvx's proxy in place of yours. On a machine that reaches the internet only through a proxy, a contained install could reach nothing. When HTTPS_PROXY or HTTP_PROXY is set, an allowed connection now goes through that proxy as a CONNECT tunnel, with Proxy-Authorization from the URL's user and password. NO_PROXY hosts and loopback destinations are dialled directly. The allowlist still decides first, so a host it refuses is never sent to your proxy.
  • On Windows, a program your own code leaves running in the background now outlives the command. Through nvx it was killed the moment the command exited. That hit npm run scripts that start a program, spawn with detached: true, and tools that start a daemon and return. Measured on 2026-10-01, an npm run script of start "" ping.exe -n 20 127.0.0.1 left 1 ping running with plain npm and 0 through nvx. A node script spawning ping with detached: true gave the same 1 and 0. Both now leave 1 through nvx.

When nvx ends a command itself, because the program that started nvx has gone, or when nvx is killed while the command runs, the command's whole process tree still ends with it. A command nobody is waiting on is still not left behind.

  • The pre-install checks now run on every package an npm install brings in. They ran on the packages named on the command line, so npm install tsx installed esbuild and ran its postinstall with no prompt, while npm install esbuild asked first. Its release age was never looked at either. For npm install, npm update and npm dedupe, nvx now runs npm's own resolver first with --package-lock-only --ignore-scripts, contained like the install, on a scratch copy of package.json and the lockfile. Every package in the tree it writes gets the blocklist, typosquat, release-age, install-script and advisory checks, with the same prompts as a package you named, apart from those already installed at the same version. A failed resolution is asked about like a failed registry lookup, and refused when nobody is there to answer. Projects with npm workspaces or a dependency on a local folder are not resolved, and the run says so.
  • A lockfile entry must now match the registry's record of its name and version. The checks read each entry's name and version and never its resolved URL or integrity hash, which are what npm installs from. An entry named left-pad@1.3.0 that pointed at the is-number tarball was checked as left-pad and installed is-number. An entry's hash must now equal the registry's hash for that name and version, or its URL must be the registry's tarball when it has no hash. One that does not is refused. Entries from git, a local path, or a URL the dependency asked for are reported as not registry-checked.
  • Without a lockfile, the checks read the version package.json declares. They read only the names, so esbuild pinned at 0.20.0 was checked as 0.28.2, the newest release. A file:, link: or workspace: dependency was looked up in the registry by name, so a local evil-pkg was flagged for an unrelated registry package of that name. Each dependency is now checked at its declared version or range, and local and workspace dependencies are not looked up.
  • npm update, npm dedupe, npm rebuild, npm exec, npm create, npm init <initializer>, pnpm dlx, yarn dlx and bun x now get the pre-install checks. They were contained and checked nothing. npm update and npm dedupe are resolved by npm as above. rebuild checks what the lockfile says is installed. The runners check the package they run, as npx does, and create foo checks create-foo. pnpm, yarn and bun update, upgrade, dedupe and rebuild check the packages they name, or the project's declared dependencies.
  • blocked_packages now applies to packages that do not come from the registry. left-pad@github:user/repo, left-pad@https://... and a registry tarball URL for left-pad all install left-pad, and none was compared with the list. The name a spec installs under is now checked, from the command line, from package.json and from the lockfile.
  • An unreadable lockfile no longer sends the checks to package.json. When package-lock.json could not be parsed, nvx checked the newest version of each name in package.json instead, and refused versions nobody was installing. That is how npm ci in a docs site was stopped over @astrojs/starlight 0.42.5 while its lockfile pinned 0.42.1. It is now asked about like a failed registry lookup, and refused when nobody is there to answer.
  • On macOS a contained install can no longer read your credential files. The macOS sandbox allows filesystem reads so programs can load system libraries, and that included ~/.npmrc, ~/.ssh, ~/.aws and the other places registry tokens, keys and cloud credentials live. Windows and Linux already kept them out of reach. The macOS sandbox now refuses reads of the npm, yarn, pnpm and bun config files, ~/.docker/config.json, ~/.netrc, ~/.git-credentials, and everything under ~/.ssh, ~/.aws, ~/.gnupg, ~/.config/gh, ~/.kube, ~/.config/gcloud, ~/.azure and ~/Library/Keychains. Other files outside the project stay readable on macOS.
  • A contained install can no longer write the project's .git. The project directory was writable as a whole, .git included, and git runs outside the sandbox. So a hook or a .git/config entry written by an install ran as you on the next git commit or git status, at the strict level too. .git is now read-only to contained runs on Linux, macOS and Windows, and so is the git directory a .git file names inside the project. Reads still work. A run that cannot protect .git refuses to start. Hook installers that run during an install (husky's prepare, simple-git-hooks, lefthook) can no longer set themselves up inside the sandbox, so run them yourself afterwards. On Windows .git stops inheriting permission changes from the project folder.
  • More package-manager commands that run dependency code are contained. nvx contains a package-manager command when it recognises the verb, and several verbs that run dependency install scripts ran uncontained with no pre-install checks. bun pm trust and pnpm approve-builds run the scripts the install held back. npm uninstall, npm prune, pnpm remove, pnpm fetch and bun remove re-install whatever the lockfile lists that is missing. npm link <package> and bun link <package> install as well, and npm pack of a git dependency runs its prepare script. These verbs and their aliases in npm, pnpm, yarn and bun are now contained. corepack is now wrapped too, and corepack pnpm add x or node "$npm_execpath" install x is judged as the package-manager command it runs. npm link, pnpm self-update and pnpm env use write outside the project, so a contained run of one is refused before it starts and names the --no-sandbox command to use instead.
  • Killing nvx on Linux now stops the contained process. The sandbox supervisor was started with no parent-death signal and no signal forwarding, so kill or kill -9 on nvx left the contained process running, and the next nvx run deleted its home directory underneath it. The supervisor now dies with nvx, SIGINT, SIGTERM and SIGHUP reach the contained process so it can shut down, and the session record names the supervisor as well as nvx.
  • A command run outside the sandbox now stops with nvx on Linux and macOS, and reports a signal as 128 plus its number. kill on nvx left the real node running, and a runtime ended by SIGTERM exited 255 where a shell shows 143. nvx now passes SIGINT, SIGTERM and SIGHUP on to the runtime, and on Linux the kernel kills the runtime if nvx is killed outright. The same exit code mapping applies to contained commands.
  • nvx doctor now tests a real sandbox launch on Linux, and explains a refusal on Ubuntu 23.10 and later. It used to report a healthy sandbox without starting one. It now runs a contained process, and when the kernel refuses the namespaces it names kernel.apparmor_restrict_unprivileged_userns, offers relaxing it or setting isolation.network.mode to open, and says whether open starts on that machine. macOS is unchanged.
  • On Linux, a contained process can no longer reach the host's UNIX sockets. Landlock below ABI v9 does not restrict connecting to a UNIX socket by path, so a contained process could open /var/run/docker.sock or any other socket on the machine while its writes stayed blocked. The sandbox now sees only the directories it is granted, and every other path on the host is absent from it. nvx's own proxy and --connect sockets live in the sandbox's home and keep working. On kernels with Landlock ABI v9, sockets in the system and runtime directories are refused as well.
  • The first nvx install now becomes the default version. With no default set, node ran an unrelated system node or failed with "Could not find real executable for node" and no hint. The first version installed for a runtime is now its default. Installing a version that is not the default says how to switch to it, with nvx use <version> for this shell and nvx default <version> for new shells. nvx doctor also exits non-zero when no runtime is available behind node, npm or npx, where it used to report that nvx was intercepting correctly.
  • zsh switches version as soon as a terminal opens inside a project. The zsh hook only ran on a directory change, so the project's version applied after the first cd. The integration now runs the hook once when it loads, which matches bash.
  • A .nvmrc with lts/* or lts/<codename> no longer prints a false "shell integration is not active" warning. Every node, npm and npm run in such a project warned, even with the right version running. The aliases are now resolved against the installed versions, so a pin that is satisfied gives no warning.
  • nvx install and nvx use with no version read the project's version file. They answered "Please specify a version" in a directory whose .nvmrc named one. They now read .nvmrc, .node-version, .bun-version and package.json the way nvx auto does. node and stable now mean the newest version, as in nvm, and nvx use iron accepts an LTS codename for an installed version. When a .tool-versions file or devEngines.runtime is present, nvx says it does not read it.
  • nvx default no longer says to add the current link to PATH. Only the shim directory belongs on PATH, and a runtime directory ahead of it is what nvx doctor reports as shadowing the shims.
  • nvx cleanup and nvx install remove what an interrupted install left. A killed install left a .tmp.<pid> staging directory, its download and a lock, and nothing removed them. Both commands now remove staging directories and downloads whose process is gone, and locks nvx can prove are abandoned. Anything whose process is still running, or whose owner cannot be read, stays.
  • nvx refuses to install the glibc build on Alpine. On a musl system the install reported success and node then failed with fork/exec ... no such file or directory. The install now stops and says the system uses musl and that nvx has no musl build. nvx does not download musl builds.
  • Colour codes and the download bar stay out of pipes and logs. Output is plain when it is not a terminal, and NO_COLOR is honoured. A download that is not on a terminal prints a line per tenth of the file instead of a bar redrawn with carriage returns. The text of the messages is unchanged.
  • -y, --agent-mode and NVX_YES no longer approve pre-install checks silently. The typosquat, release-age, install-script, known-advisory and "could not check" prompts were answered with no output and no audit record, so nvx audit read "No audit records yet" after an install that had gone past all of them. Every one of these checks now writes a check_approved or check_refused record, however it was answered and whatever NVX_TRACE says. An approval nobody was asked about also prints one line to stderr that names it.

A refusal now names the narrowest fix first, as the exact policy line to add, and mentions -y and NVX_YES last. That covers typosquatting.trusted_packages, release_age.trusted_packages, install_scripts.trusted_packages, vulnerabilities.allowed_advisories and min_severity, and isolation.network.allow_hosts for a refused host. The enforce_ignore_scripts refusal used to say to run with --ignore-scripts, which does not get past it, and now says what does. The reply sent to an MCP client and SECURITY.md follow the same order.

A failed weekly-download lookup (a 429, a proxy block, no network) used to fall back to name similarity without saying so. The prompt now says the lookup failed and that the result is a name-similarity guess. A name on nvx's popular-package list is warned about instead of flagged. A name on no list is checked as before.

  • Cleanup no longer removes a running session's files on Windows. A session whose owning process nvx could not open, such as an elevated one, was read as finished, and its home could be deleted while it ran. A trusted tool's AppContainer profile could also be deleted while the tool was running, once it had gone unused for the retention window. Each trusted-tool run now marks itself as live for as long as it runs.
  • Two runs of one trusted tool no longer share stdio pipes on Windows. The pipe names came from the tool's home, which is the same for every run, so a second run joined the first one's pipes. Each run now draws its own names, and a name already in use is refused.
  • nvx setup checks that the old loopback exemption is really gone. Any failure to remove it, a timeout included, was reported as nothing to remove. Setup now reads the exemption list and fails while the exemption is still registered. nvx setup --undo also removes the grants setup recorded, which included the Users folder on other volumes, and no longer leaves an unused AppContainer profile behind. nvx doctor now says leftover sandbox permissions on a project admit sandboxes from nvx builds older than 0.5.0, which is who they admit.
  • nvx doctor --fix keeps non-ASCII entries in your User PATH. It read the PATH through reg query, whose output is in the console code page, so C:\Users\Jürgen\bin came back with a wrong byte in place of the ü, and the repair wrote that back. It now reads the value directly from the registry.
  • An unreadable grants record is no longer replaced with an empty one. A record that existed and could not be read was treated as empty, and the next change saved over it, losing the list of permissions nvx had granted. The change now fails instead, and read-only commands warn.
  • The egress proxy refuses a malformed CONNECT port. 443x went on as port 0 and 99999 as 65535, and the raw request, port included, was printed to the terminal when the dial failed. It now answers 400 and logs only the parsed host and port. The proxy also checks its credential before it judges the host, so an unauthenticated caller can no longer put a warning on your terminal or a line in the audit log.
  • nvx audit export --format csv no longer emits spreadsheet formulas. A value starting with =, +, - or @ became a live formula when the file was opened in a spreadsheet, and several fields can come from lines anything on the machine appended to the log. Such cells now start with a single quote.
  • A project bin with a dot in its name gets a working shim. A node_modules/.bin entry named foo.bar was shimmed as foo, which ran a command nothing provides. Only .cmd, .ps1 and .exe are trimmed now.
  • bun@0.8 and other older Bun lines resolve again. Only the first 100 Bun releases were read, and that page now ends at 1.0.25. The whole list is read.
  • A refused isolation.environment.allow entry is recorded in audit.log. A policy asking to pass a credential into the sandbox was a terminal warning and nothing else. It is now an env_pass_refused record, with names only.
  • Smaller Windows fixes. The hangup watchdog no longer waits on an unrelated process that reused its parent's pid. A contained command's exit no longer waits up to 5 seconds per stuck stdio channel, one after another. A failure to stage the command now has its own reason in the audit log. The icacls command nvx suggests for a widened read/execute entry can be pasted as printed.
  • A package installed under an npm alias is checked as itself. npm install myalias@npm:left-pad was checked as a package called myalias, so a blocklist entry for left-pad did not stop it, and the typosquat, advisory and release-age checks asked about a package that does not exist. The same alias in package.json or package-lock.json was read the same way by npm ci and by nvx policy check. The target package and its version are what gets checked now.
  • nvx NPM install x gets the same checks as nvx npm install x. The command name was accepted in any case and ran contained, and the pre-install checks only matched it in lowercase, so they were skipped.
  • nvx policy check fails when package.json or package-lock.json does not parse. It warned and exited 0 having checked no dependency. It now reports an internal_error (exit 1). Run from a subdirectory, it also reads the project root's files, as the package manager does, instead of finding none.
  • -y and --agent-mode no longer approve a persistent tool profile. The help says only NVX_TRUST_YES approves trusting a tool, and this one prompt was answered by the ordinary -y.
  • The prompt to trust a project policy says what the file loosens. It named the file only. It now lists each setting with its value before and after, for example typosquatting.enabled: true -> false.
  • A policy key in the wrong case is no longer reported as ignored. {"Isolation": {"Enabled": false}} switched containment off, because JSON keys match in any case, while nvx warned the key was "being ignored". It now says which setting the key applies to and asks for lowercase.
  • nvx policy init in a project no longer overrides the global policy. It wrote every default into .nvx-policy.json, so under a stricter global policy the file loosened it, and under an enforced one every command in the project was refused. It also replaced the runtimes' own default hosts. The project file it writes now sets nothing until you add to it.
  • An enforced global policy is not widened by hosts approved earlier. Hosts a project had approved at a prompt were added after the enforcement check, so they reached the network past the baseline. Under enforcement nvx now drops them and says so once.
  • allow_read_exec refuses an entry that would grant a whole drive or home. An entry using an unset variable collapsed to a filesystem root: %UNSET%\ became C:\ and $UNSET/ became /. ~ alone granted the whole home directory. These are now refused with a warning, as is a directory that holds the nvx home.
  • A version range with a space after the operator is accepted. ">= 18", common in package.json engines, failed with "empty version". The error for a range that really cannot be read now names the text.
  • The version-pin warning no longer reports npm's version as node's. With a .nvmrc asking for 22, an npm command warned it was "running 10.9.2", which is npm's own version.
  • The quickstart no longer promises read containment on macOS. It said installs run with "no access to your keys" on every platform. The macOS sandbox does not contain reads, so there it now says what holds.
  • nvx use --shell bash 20 switches to 20. It took bash as the version.
  • nvx grants list says when the grant record cannot be read. It printed "(none)" for every kind of grant, which reads as nothing granted.
  • The help names every --filesystem-provider. It listed native and docker and left out sandbox-exec, the macOS one.
  • nvx import asks about only the versions it would download. Its prompt counted versions nvx already had.
  • nvx policy explain no longer cuts a character in half. A long value was shortened by bytes, which split a non-ASCII character and printed invalid text.
  • The Docker check has a time limit. docker info ran without one, so a daemon that accepted the connection and never answered held the command with no output. It now gives up after 15 seconds.
  • npm install --location=global and bun add -g are refused up front. They are global installs like npm install -g, and went into the sandbox instead of getting the same clear refusal.
  • A cached command path must name the command. The cache of resolved command paths accepted an entry for node that pointed at any program in a PATH directory. It now requires the file name to match. Its temporary file also has a unique name, so two nvx processes saving at once cannot rename each other's half-written file into place.
  • nvx audit --limit 5 works like --limit=5. Export already took both spellings. An over-long last line with no newline after it is now counted as malformed rather than dropped without a word.
  • nvx use 99 no longer offers to install a version that does not exist. It asked whether to download and install Node.js 99. It now checks the release index first and says no published release matches.
  • --help after any command prints that command's help. nvx install --help printed help and nvx list-remote --help failed with "Unknown option". Commands without a page of their own now print their entry from nvx help.
  • nvx doctor prints its PATH fix in Git Bash syntax under Git Bash. On Windows it always printed the PowerShell form, which bash cannot run.
  • A contained spawn keeps the stdin descriptor its caller passed in. In the Windows sandbox, spawn(cmd, args, {stdio: [fd, 'pipe', 'pipe']}) closed fd once the child started, so a file the caller opened and handed to the child as stdin could not be read again. The sandbox now closes only the descriptors it opened itself, and removes the temp folder behind an empty stdin when the child closes.
  • Two installs that find the same abandoned lock no longer both proceed. nvx clears an install lock left by a process that has gone. On Linux and macOS two waiters could both read the dead owner, and the second removed the lock the first had just taken, so both extracted into one directory. Clearing a lock is now serialised.
  • On macOS a SIGTERM sent while nvx starts the sandboxed command reaches that command. nvx installed its signal handler after starting the child, so a signal in between killed nvx and left the child running. The handler is now in place first.
  • A slow disk no longer reads as a stalled download, and a stall can no longer crash nvx. The stall timer ran between reads too, so time spent writing the archive counted as the network going quiet. If it fired, a read that then returned data re-armed it, and a second firing crashed the process. The timer now runs only while nvx waits for data, and fires its signal once.
  • A version name ending in a dot is refused. Windows drops trailing dots from a path component, so v20. names the v20 directory and ... names the versions folder itself. On Windows, listing a\... returned the contents of a. No real version ends in a dot.
  • A socket path too long for Linux says so. A deep NVX_HOME made the sandbox's egress and --connect sockets fail with a bare "bind: invalid argument". nvx now reports the path's length against the 107-byte limit and says to set NVX_HOME to a shorter directory, as it already did on Windows.
  • install.sh refuses a CPU it has no build for. On armv7l, i686, riscv64 or any other CPU it installed the x86_64 binary, which cannot run there. It now stops and names the architecture.
  • install.sh says so when it has no way to check the download. With neither sha256sum nor shasum installed it reported a checksum mismatch. It now looks for one before downloading and says which to install.
  • install.sh no longer writes lines fish cannot read. For a fish user it added POSIX lines to ~/.profile, which fish never reads, and reported the profile as updated. It now prints the fish_add_path command to run.
  • The one-line Windows install leaves your PowerShell session as it was. Run as irm ... | iex, install.ps1 left $ErrorActionPreference = 'Stop', a TLS 1.2-only connection setting, and its own variables and functions in the window it was pasted into. It now runs in a scope of its own and puts the TLS setting back.
  • Homebrew and Scoop releases are checked against their build provenance. Only the npm publish checked that a binary was built by release.yml. The Homebrew and Scoop jobs trusted a .sha256 file from the same release page as the binary, so a binary replaced there together with its checksum would have been published. All three now require the attestation release.yml made for the binary.
  • nvx grants reset --all works after a grant has been recorded. It read the lock file kept beside each grant record as a record of its own, failed to parse it, exited 1 and said to remove permissions with icacls by hand, on every run after the first grant. It now skips lock and temp files, and both reset forms hold the record's lock while they read, withdraw and delete it, so a grant saved at the same moment is not deleted with it.
  • nvx doctor no longer calls a bypassed command healthy. It listed [FAIL] npm -> ... (bypasses nvx) and then said "nvx is intercepting commands correctly" and exited 0, because it only counted nvx's own runtime folders as shadowing. A system Node earlier on PATH, the usual Windows layout, now makes doctor exit non-zero.
  • Every spelling of an install is contained and checked. Plain yarn and yarn --frozen-lockfile (yarn's default command installs), npm x, npm clean-install and ic, npm it, cit and sit, npm rb, and npm's isntal and udpate typo aliases ran as your own code: no sandbox and no pre-install checks. They now run as the install or tool run they are.
  • exec() and execFile() no longer hang inside the Windows sandbox. node's own versions call a spawn the sandbox's preload could not reach, so they took the path that blocks forever before the child exists. A contained exec('cmd /c echo hi', cb) never called back, and neither did a timer set before it, while the same call uncontained answered in 300ms. node-gyp finds Python this way, and many install scripts shell out the same way. Both are now rebuilt on the sandbox's working spawn, with the same callback, error, timeout, maxBuffer and promisified behaviour as node's. A streamed child's close event also waits for its output again: it fired when the child exited, while nvx was still passing the output along, and a CI run saw 1 line of 200 arrive by then.
  • A contained command started in your home directory can no longer write it. The working directory is writable inside the sandbox, and nothing checked which directory it was. From ~ or /, where editors often start MCP servers, a contained process could write ~/.nvx (its grants and policy, so the next run's trust) and ~/.bashrc. Measured on Linux and on a macOS runner: from a project all three writes were refused, from the home directory all three landed. nvx now starts such a command in the sandbox's home and says why. The same rule applies on Windows to a directory above the profile or inside ~/.nvx. The Linux and macOS enforcement scripts check it on every CI run.
  • Windows: granting the sandbox access no longer opens your profile to other accounts. Every permission nvx wrote on a folder switched that folder's inheritance protection off. Windows ships C:\Users and each profile folder protected, so they do not take the drive root's "Authenticated Users: Modify". One nvx setup grant on C:\Users, or one traverse grant on a profile, lifted that, and every signed-in account on the machine could then read and change the whole profile. nvx now keeps a folder's protection as it found it, and nvx doctor reports a profile, or the folder above it, that has lost its protection, with the icacls ... /inheritance:r command to restore it when the folder's own entries keep you in.
  • The one-line Windows install works. irm https://nvx.run/install.ps1 | iex stopped every time with "Cannot bind argument to parameter 'Path' because it is an empty string": the script read its own directory, which iex does not have. It had already edited PATH and the PowerShell profile by then. The installer now downloads and verifies nvx first and changes nothing if that fails, and CI runs the whole script through Invoke-Expression. It also no longer offers nvx setup at the end with a warning that package managers "run without OS isolation" until you do. That was false: installs and npx run contained without it.
  • The Linux sandbox runs the system's ip and iptables, not the first ones on your PATH. It set a system-only PATH for the child, which does not change which binary starts: that is looked up in nvx's own PATH. They are now taken from /usr/sbin, /usr/bin, /sbin and /bin only, as Windows already does for its system tools.
  • A contained process can no longer hold nvx's egress proxy open by sending nothing. The proxy waited indefinitely for a request's headers; it now allows 5 seconds for the handshake, the same bound the Linux loopback redirect uses, and none once the tunnel is open.
  • --connect works in network.mode: loopback on Linux. It was refused on the grounds that the mode denied the sandbox every IP socket, which stopped being true when loopback moved to the proxy filter on 2026-09-08. Measured 2026-09-25 in WSL: the previous binary refused the flag; this one carried a request to a service on the host's 127.0.0.1:7788 and got its reply.
  • Bun accepts version ranges, and ^0 means what npm means. nvx install bun@^1.1, and any engines.bun range, failed with "no Bun release matches" because Bun's resolver took only exact versions and prefixes; it now takes the same ranges Node does. ^0 and ^0.0 allowed only 0.0.0; they now mean <1.0.0 and <0.1.0, as in npm.
  • network.mode: offline means no network, allowlist included. The egress proxy checked the allowlist before the mode, so an offline run that reached it got every allowlisted host, and on Linux its socket was offered in offline mode with only seccomp in the way. The proxy now refuses everything in offline mode, and Linux no longer offers the socket there, as Windows already did not.
  • nvx import fnm finds fnm's Node versions. fnm keeps them in a node-versions directory under its base directory, and the import looked in the base directory itself, so on a standard fnm install it found nothing. It now reads node-versions under FNM_DIR, the platform data directory, ~/.fnm, and on macOS ~/Library/Application Support/fnm.
  • nvx uninstall no longer removes the Node version your shell is using when Bun comes first on PATH. The guard read the first nvx runtime on PATH whatever it was, so with Bun ahead it compared Bun's version and let the active Node go. It now checks Node's own entry, as Bun's uninstall already checked Bun's.
  • Smaller fixes. nvx import exits 1 when every install it tried failed. A truncated download of the typosquat package list is no longer cached as the whole list, and the cache is written atomically. A failure to write the audit log is reported once instead of silently dropped. --connect refuses to start when it cannot pick an in-sandbox port, instead of advertising port 0.
  • A policy can no longer pass GH_TOKEN or STRIPE_SECRET_KEY into the sandbox. isolation.environment.allow refused credential-looking names by their start only (GITHUB_, AWS_, ...), so names whose secret-ness is at the end got through: GH_TOKEN, SENTRY_AUTH_TOKEN, STRIPE_SECRET_KEY, PGPASSWORD. Names containing TOKEN, SECRET, PASSWORD, PASS, CREDENTIAL or APIKEY as a word, API_KEY / ACCESS_KEY / PRIVATE_KEY, or ending in TOKEN, SECRET or PASSWORD are now refused the same way. TOKENIZERS_PARALLELISM, MAX_TOKENS and AUTH_URL still pass.
  • A failed install no longer closes your PowerShell window or removes your nvx. irm ... | iex ended with exit, which closes the session it runs in, so the error vanished with the window; it now reports the error and leaves the window open. install.sh downloaded over the existing binary and deleted it when the checksum did not match, leaving no nvx; it now verifies the download beside it and replaces nvx only on a match.
  • npm ci spends less time in nvx's package checks. Every lockfile entry is checked against the registry, and those requests went one at a time. They now run eight at once, ahead of the checks, which still ask their questions one at a time and in order. Measured 2026-09-24 on a 651-entry lockfile with npm ci --dry-run: 34.5 s and 32.7 s before, 11.0 s to 13.1 s over four runs after.
  • Old staged copies of commands are cleaned up on Windows. A contained command from outside nvx's own runtimes, such as a system Node or Bun, runs from a copy of its whole directory, and every update to it left the previous copy behind for good. The largest of four on the development machine was 31,814 files and 451 MB. Copies whose command has changed are now removed, one after each contained command and all of them by nvx cleanup. A copy something is still running is left until it stops.
  • Only a runtime's own files are copied for the Windows sandbox. The copy of a system Node or Bun was the command's whole folder, and every sandbox on the machine can read it, so anything kept beside the runtime went with it. nvx now copies the executables, the npm and npx wrappers and node_modules, and refuses a command whose folder has no node.exe or bun.exe rather than copying it. node, npm and npx from one install now share one copy: they made three before, 1.6 GB each for the nvm install on the development machine. Existing copies are replaced on next use and the old ones pruned.
  • The Linux sandbox's network filter covers x32 and io_uring. It matched system calls by their x86-64 numbers only, so the same call made through the x32 ABI or submitted through io_uring went past it. On a kernel with x32 enabled, a contained program in network.mode: offline could open a TCP socket and connect to nvx's in-sandbox relay. It reached nothing beyond that, because the relay's own outbound connection was still refused. Calls from a foreign ABI are now refused, and io_uring reports itself unavailable, as it does on a kernel built without it.
  • nvx default works when the home path contains &. On Windows it made its junction through cmd /c mklink, and cmd.exe split the path at the & and ran the rest as a command. With a home like C:\Users\A&B, the text after the & ran and the default was never set. nvx now writes the junction itself.
  • The Windows installer no longer leaves a binary that failed its checksum. A download whose SHA-256 did not match stayed in ~/.nvx/bin after the installer reported the failure, and -InsecureSkipChecksum, meant for a release with no checksum file, installed it. The download now goes to a side file and replaces nvx.exe only after it verifies, so a failed upgrade also leaves the previous binary working. A checksum that is present and wrong fails with or without the flag.
  • A package can no longer put its own git ahead of yours. nvx refuses to wrap a node_modules/.bin entry whose name already resolves elsewhere on PATH, and the check stopped at the first match. Inside any npm script that first match is the project's own node_modules/.bin, so a file a contained install dropped there as git was taken for the project's copy and wrapped onto PATH ahead of the real one. The next git typed in that project ran it outside the sandbox. The check now looks past every directory inside the project. Measured 2026-09-23 on Windows: the same planted file is no longer wrapped, git resolves to Git for Windows, and an ordinary project CLI is still wrapped.
  • Contained commands on Linux can write to /dev/null. It was granted read-only, so >/dev/null in any shell script failed, and so did every Node spawn with stdio: 'ignore', which opens it for writing. Measured on Linux 6.18: both failed with EACCES inside the sandbox before, and both work now. The other devices stay read-only.
  • The Linux sandbox forks the contained command from the thread it restricted. Landlock, no-new-privs and the private /proc mount each apply to one OS thread, and nothing kept nvx on that thread, so the command could start from another one with none of them in force. This was not reproduced through nvx itself. The same sequence in a standalone program on Linux 6.18 let 164 of 300 children create a file Landlock should have refused, and 0 of 300 once the thread was pinned, which nvx now does.
  • yarn install runs inside the Windows sandbox. yarn classic fetches from registry.yarnpkg.com, a front for the npm registry, and that name was not on the default allowlist, so every contained yarn install was refused on its first fetch and gave up after four retries. It is allowed by default now, next to registry.npmjs.org. Measured 2026-09-17 with yarn 1.22.19: a bare install of one dependency exits 0, and so does the second run.
  • A tool on Node 18 can stat nvx's own directories from inside the Windows sandbox. The entry nvx writes on the directories above a contained command's home let it pass through them and read their attributes, but not the SYNCHRONIZE right that every CreateFile asks for. A runtime that opens a directory to stat it, which libuv did until 1.44, got EPERM on ~/.nvx and ~/.nvx/sandbox_home; newer runtimes list the parent instead and never noticed. pnpm's standalone binary bundles Node 18.5 and died on that stat before doing anything. The entry carries SYNCHRONIZE now, and ~/.nvx itself gets one, written without the propagation over everything beneath it that used to time out: 22.3 s for the propagating write against 1.07 ms without, measured back to back. A first pnpm install in a fresh project exits 0. A second one still does not, for a reason no permission fixes; see Known limitations on the docs site.
  • A project directory deleted and recreated no longer fails to launch on Windows. nvx remembered for seven days which directories already carried its sandbox permission, in ~/.nvx/grant-cache.json, and trusted that record without looking at the directory. A fresh clone into the same path, a CI workspace, or a new worktree has no such permission, so the grant was skipped, nothing was logged, and the contained process could not enter its own working directory: AppContainer launch failed ... The parameter is incorrect. Every package manager failed this way, npm included. Reproduced with the previous binary on 2026-09-17 by deleting and recreating a project directory between two runs.

The record is gone. Every check reads the directory's real permissions, which was measured at under a millisecond a path; warm launch times before and after the change were within run-to-run noise of each other. The old cache file is no longer read and can be deleted.

  • Contained commands work again from inside AI agent shells on Windows. Every contained launch asked Windows for CREATE_BREAKAWAY_FROM_JOB, and a process inside a job object that forbids breakaway — which is how Claude Code, Codex CLI and similar harnesses run every command — is refused with a bare Access is denied before anything is created. From an ordinary terminal the same command worked, which is why it read as a machine problem for weeks: memory, disk, ACLs and a security product were each ruled out on the way to measuring it directly (2026-09-20: plain cmd.exe from such a shell — fine without the flag, denied with it). nvx now asks to break away only where the calling process's job permits it. A child that stays in that job is still reaped through nvx's own nested job.
  • A command the sandbox refused to run is no longer logged as having run inside it. The run record's mode is decided before the sandbox is asked to start, and nothing corrected it when the start failed, so nvx audit showed sandboxed npm install exit=1 for a command that never began — the same line a fully contained install failing on its own terms produces. Measured on 2026-09-20 against a host that could not launch an AppContainer at all. Those runs now read refused, and carry the reason.

runSandbox's own refusals — an unknown filesystem provider, a provider that cannot enforce the requested network mode, an egress proxy that would not start — wrote nothing to the audit log at all. They now record a reason like every other refusal does.

  • The test suite no longer writes nvx's shell integration into your real PowerShell profile. nvx doctor --fix repairs two things a throwaway NVX_HOME does not contain: the persistent PATH, and the shell profile. The PATH write was given a test seam after it was caught prepending dead temp directories to real user PATHs. The profile write was not, and kept going.

Redirecting HOME does not reliably contain it. On Windows nvx asks PowerShell for $PROFILE, and where that lands depends on the machine: a CI runner's PowerShell follows the redirected home, while one whose Documents folder is redirected to OneDrive does not and answers with the real profile. A test cannot tell the two apart, so any test reaching doctor --fix could append the integration line outside its own temporary directory.

It is plainest in CI, where the runner starts clean: the Windows job's unit-test step logged Added the shell integration to C:\Users\runneradmin\Documents\PowerShell\Microsoft.PowerShell_profile.ps1, and every later PowerShell step in that job then printed The term 'nvx' is not recognized at startup, loading a line a test had planted.

The write is now replaceable in tests, the way the PATH repair already was, and the tests that run doctor --fix replace it. Nothing about the shipped behaviour of nvx doctor --fix changes.

The check that keeps it that way parses the test sources rather than matching them with a pattern. A review caught the pattern version passing in two cases, both then reproduced: a caller written the ordinary way for this suite, runDoctor(tempDir(t), true), never matched at all, because the expression could not cross a nested bracket; and the stub was looked for anywhere in the same file, so one careful test excused every other caller beside it. It now looks per function, fails when it finds no callers at all rather than passing by looking at nothing, and covers the remaining route — a test that runs the built binary, where an in-process substitute cannot reach.

Two reasons it went unnoticed on developer machines, both accidents rather than protection: under Git Bash MSYSTEM is set, so nvx picks bash and the PowerShell branch never runs, and a developer's profile usually already loads nvx, so the check short-circuits before writing.

  • The Windows installer no longer changes your PowerShell execution policy without asking. It set the policy to RemoteSigned behind a progress line, with -Force and errors suppressed. That is the setting PowerShell uses to decide what code it will run, and an installer should not move it on your behalf; suppressing the error also meant a failed change read exactly like a successful one, leaving the shell integration dead with nothing saying why.

It now explains what the change does and why nvx wants it, asks, and reports what actually happened. Declining still installs nvx, and prints the one command to run later. A non-interactive run changes nothing.

It also asked the wrong question. The check read the CurrentUser scope, which is Undefined on any machine whose policy is set elsewhere — measured on a developer machine on 2026-09-11: CurrentUser Undefined, effective RemoteSigned, scripts running fine. It now reads the effective policy, so a machine that is already fine is left alone.

  • build-release.ps1 stamped builds with a version from eight tags ago. Its -Version default was the literal 0.5.0, written once and never revisited, so any local build since has reported a version it was not. The default now comes from version.go, which a test already holds equal to the newest changelog entry, so the binary, the changelog and the build script cannot disagree. Published releases were never affected — those are built by the release workflow, which takes the version from the git tag.
  • Windows: a contained launch could be refused because the machine briefly could not create a process. prepareAppContainerFilesystem labels the guest home by running icacls, and when Windows momentarily runs out of handles that call fails at fork/exec with The handle is invalid — the command never starts. nvx reported it as a launch failure, so the sandbox refused to run for a condition that clears by itself.

Measured on a hosted runner on 2026-09-09, in the same second that AppContainer launches were being refused and two probe children returned no output at all; the same commit re-run was clean. nvx already treated this exact error as transient when reading the staged probe child, and as fatal when creating a process — that asymmetry is what this closes.

Retried five times at 200ms, the shape already used elsewhere, and only when the error says the process was never created (fork/exec plus ERROR_INVALID_HANDLE). That is what makes re-running safe whatever the command would have done. A missing executable also fails at fork/exec and is still reported at once rather than after five waits, and the errno is matched rather than the English text, which differs on a localised Windows.

  • blocked_packages understood only a trailing *. Every other policy list goes through one shared matcher that takes * and ? anywhere; the blocklist had a matcher of its own that recognised a literal name or a trailing star and nothing else. So "*-malware" and "evil-?-pkg" parsed, validated, produced no warning, and blocked nothing. The asymmetry ran the wrong way -- the lists that widen access understood more syntax than the list that withdraws it. The blocklist now uses the shared matcher.
  • Approving a registry-metadata failure also gave up the vulnerability scan, without saying so. When nvx cannot resolve a package's metadata it asks whether to proceed; approving skips the rest of the checks for that package, including the OSV advisory lookup, because advisories are queried by exact version and the version is what could not be resolved. The question named only "metadata checks", so a run could report nothing about a package it had never asked about. nvx cannot scan without a version; the prompt and the warning now say that is what approving costs.
  • A zsh user is now treated as a zsh user. With no --shell given, nvx on Linux and macOS chose bash unless SHELL named fish. Someone on zsh, the macOS default, who ran nvx use 20 without the integration was told to add the line to ~/.bashrc, and nvx doctor --fix wrote it there, where zsh never reads it. nvx now selects zsh when SHELL ends in zsh. The hint names ~/.zshrc and nvx doctor --fix writes to it.
  • nvx doctor --fix writes the same fish file as the installer. For fish it wrote only the nvx env --shell=fish | source line. The installer's conf.d/nvx.fish also puts ~/.nvx/bin on PATH first, and without that fish cannot find nvx when the line runs. doctor now writes the installer's whole file. A file that already loads nvx, in either form, is left alone, so one an earlier doctor --fix wrote keeps the line-only form until you delete it and run nvx doctor --fix again.
  • On Linux, the refusal for a long NVX_HOME names the longest one that works. A socket path must be shorter than 108 bytes, and the refusal only said to use a shorter NVX_HOME, leaving you to guess how much shorter. It now says Set NVX_HOME to a directory of at most N characters (it is M), as the Windows refusal does. N leaves room for the longest socket the run creates, so following it does not meet a second refusal. The loopback socket used to fail with a bare bind: invalid argument and now gets the same check. Where the sockets live on Linux has not changed.

v0.6.0

Sep 9, 2026

Per-project sandbox identity, and the first ways for a contained tool to reach named things outside its box: --connect for one service, loopback mode, read-and-execute grants, and named environment variables. The wsl, wslc and systemd-nspawn providers were removed.

Added

  • install_scripts.trusted_packages and vulnerabilities.allowed_advisories: the last two install-time checks can be waived for a named target. Both are empty by default, so every check still applies to every package until a policy names an exception, and each waives only its own check.
  {
    "install_scripts": { "trusted_packages": ["esbuild", "sharp"] },
    "vulnerabilities": { "allowed_advisories": ["GHSA-xxxx-yyyy-zzzz"] }
  }

Vulnerabilities had no setting at all: a package with a known advisory prompted on every install, and the only way past it was to answer. Advisories are accepted by ID, not by package, because that matches the decision a person makes -- "this finding does not apply to how we use it" -- where exempting the package would also waive the advisory published after that assessment. A scan whose findings were all accepted reports them rather than reporting "clean".

  • vulnerabilities.min_severity: stop on the advisories that matter, report the rest. low, moderate (or medium), high or critical. Unset by default, which stops on every advisory, and that default does not change.

The rating comes from the advisory record's own severity, read from the lookup nvx already makes to fill in each summary -- so the floor costs no extra requests.

An advisory nvx could not rate stops the install at every floor. That lookup is bounded and best-effort, so an empty severity means "not measured", and treating it as low would turn a failed request, a rate limit, or an advisory past the lookup cap into a finding that quietly passed. An unrecognised min_severity is no floor at all, and is reported at load time rather than ignored.

Measured against lodash@4.17.15, whose six advisories are three HIGH and three MODERATE: with the floor at high, the three moderate ones are reported as below it and the three high ones still stop the install; at critical, all six are reported and the install proceeds. Each line names the advisory, its severity and the floor it fell under.

Words rather than CVSS scores. OSV carries both, and the words are what GitHub's advisories -- which the npm ecosystem is almost entirely made of -- always carry. Scoring a CVSS vector by hand would be a second implementation of a specification, in the one place where getting it subtly wrong means an advisory silently drops below a floor.

  • release_age.trusted_packages: skip the cooling-off window for one package, and only that. The window holds back a version published in the last 24 hours because a supply-chain compromise is usually caught inside it. Waiving it for a package you trust needed typosquatting.trusted_packages before, which also turned off typosquat detection for that name -- two unrelated judgements that could not be made separately.
  { "release_age": { "trusted_packages": ["chrome-devtools-mcp", "@upstash/*"] } }

Names and globs, matched case-insensitively, by the same matcher the typosquat list uses. Adding one counts as loosening, so a project file naming a package needs approval like any other exemption.

The case that forced it is an MCP server on a floating version. Its client starts it non-interactively, where a prompt is denied rather than asked, so a version published that morning stops the server starting with no way to answer. The alternatives were to widen the window for every package or to switch the check off.

typosquatting.trusted_packages no longer waives the release-age window. A policy relying on that will see the prompt return -- and in the non-interactive case a denial -- so when a package is in that list and the window trips, nvx names the list and says which one to move it to instead of leaving the change to be discovered.

Fixed

  • The audit log recorded every refused launch with the same reason. A real log held 73 sandbox_not_started entries, all reading "the sandbox did not start" -- the text of the sentinel error itself. That answers "was this contained?" and not "why was it not?", and it was the largest security-relevant event in the file. Found by reading one back.

Every refusal site already told the person watching what went wrong in its own words; only the machine-readable cause was missing. The launchers now attach a fixed reason to the sentinel -- the appcontainer profile was unavailable, the seatbelt profile could not be written, the loopback path could not be opened, and fourteen others -- and errors.Is still matches, so nothing that only wanted the fact of a refusal changes.

The reason is a literal chosen at the call site, never a rendered error, which is the rule LogWarn already follows for this destination: a rendered message can carry a package URL with credentials in it, and this file goes to disk. A test parses the source and fails on anything that is not a string literal.

  • Upgrading nvx while something was running from it kept the old binary, and said the upgrade worked. The copy ended in a plain rename, which Windows refuses for a file being executed, so it was abandoned with a warning -- and Generated PATH shims printed straight after, so the upgrade reported success and installed nothing. Anyone with an MCP server or a long-running command going through nvx would hit it, and the symptom is a version that does not change.

The shims already handled this: a busy file is renamed aside and deleted on a later run once nothing holds it. nvx's own binary was the one file in that directory not getting the same treatment.

The rename-aside now also puts the original back if the replacement cannot be put in its place. Between the two steps there is a moment with nothing at the destination, and leaving it that way is worse than not having tried: for a shim it is a command gone from PATH, for nvx itself every shim pointing at nothing.

Measured on Windows against a target held by a running process, the same command both ways: without the fix, "Could not update ... Access is denied" and the installed binary unchanged; with it, replaced and no warning, and the leftover cleared on the next run once its holder exited.

  • network.mode: loopback did nothing on Windows, Linux and Docker. Each treated it as offline, so a mode whose name says "the services on 127.0.0.1 are reachable" reached none of them. Windows granted no network capability and started no relay; Linux gave it the offline seccomp filter, which denies connect() outright, so the contained process could not even reach the proxy that implements the mode.

Windows and Linux now route it through the relay, exactly as proxy mode does. Neither gains any OS-level reach: Windows still holds no network capability, Linux still runs in its own network namespace, and every destination is still the parent proxy's decision. The one difference from proxy is the rule that defines the mode -- a loopback destination is allowed without an allow_hosts entry.

Linux carries raw connections too. Every loopback TCP connection in the namespace is redirected to a relay, which asks the kernel what the connection was for and carries it to the parent; the parent dials that address, and refuses any that is not loopback. So a tool reaching your local database at 127.0.0.1:5432 arrives at 127.0.0.1:5432, with nothing named on the command line and no second port number -- which is the difference between this mode and --connect.

The refusal is the enforcement point rather than a formality: the socket sits in the guest home, so a contained process can skip the relay, open it directly and ask for any address it likes.

A server the sandbox itself runs stays reachable from inside it. The relay tries the sandbox's own namespace before the host, so a contained npm run dev on 127.0.0.1:3000 and a contained test client still find each other. nvx's own listeners are excluded from the redirect, so egress does not take a hop through it.

A Linux host whose kernel will not take the rules -- no iptables, or no nat table inside an unprivileged user namespace -- falls back to the proxy-mediated reach and says so. What is lost there is reach, not containment.

Windows still covers only what a proxy-aware client sends. Its reach comes from the proxy alone, so a raw socket to a local database works on macOS and Linux and does not there. Recorded rather than smoothed over.

Docker keeps --network none in this mode, for the reason it refuses proxy: the allowlist would be advisory, since nothing stops a tool ignoring the proxy.

Measured on Linux CI twice: as a CONNECT to the proxy in both modes -- refused under the default, tunnelled under loopback -- and as a raw connection from a client that knows nothing about HTTP_PROXY, which only arrives if the redirect is carrying it. The same raw client ran under the default mode and failed, which is the control: without it, success would equally be what a sandbox with an accidental route out looks like.

  • A project policy could switch the sandbox to network.mode: loopback without approval, and on macOS that handed it every local service. The approval gate ranks the modes by how much a contained process can reach, and loopback was ranked with offline, below proxy -- so a project file changing proxy to loopback read as asking for something *stricter* and was applied silently.

It is the opposite. proxy reaches a loopback service when allow_hosts names it; loopback reaches every service on 127.0.0.1 without naming any. A .nvx-policy.json lives in the repository, so this was one line in a pull request pointing a contained install at the developer's database, their other projects' dev servers, and any local agent.

Live on macOS, where the Seatbelt profile grants all of localhost in that mode. Windows, Linux and Docker treated loopback as offline, so there was nothing reachable to hand over -- which is also why nothing caught it.

loopback now ranks between proxy and open, so selecting it asks for approval like any other loosening.

  • The docker provider no longer accepts --connect in silence. It never carried the flag: dockerRunArgs did not read the connect ports at all, so a command line or a policy asking for one launched a container that could not reach the service, with nothing on screen connecting the two. Exactly the failure the flag exists to prevent, one layer down.

It cannot carry it, and the reason is structural rather than a missing docker run argument. Every relay nvx runs has an in-sandbox half that is a process of nvx's own; the Docker provider has none, because it launches the target command as the container's only process. The container also has a network namespace of its own, and in offline and loopback -- the only two modes this provider enforces -- --network none leaves it nothing but its own loopback.

So it now says so, and names the native provider as the way to get the service.

Added

  • --connect works on Linux, in the modes that can carry it. The third platform, and the one where the sandbox is furthest from your machine: it runs in a network namespace of its own, so 127.0.0.1 inside it is a different 127.0.0.1 and no permission grants a route to yours.

The traffic crosses the way the egress proxy's already does. The supervisor listens on the in-sandbox port inside the namespace and forwards over a UNIX socket in the guest home -- a filesystem object, which a network namespace does not touch -- and nvx dials your service from outside it.

No peer check here, and for a firmer reason than on macOS: another sandbox has its own namespace and its own guest home, so neither half of this is addressable from it.

offline and loopback cannot carry it, and say so. Both modes deny the contained process every IP socket, which includes the one it would use to reach the tunnel. Making the flag work there would mean granting those modes exactly what they exist to withhold, so nvx refuses out loud and names the modes that do carry it. The default, proxy, is one of them.

scripts/sandbox-smoke.sh drives it on CI against a real service, running the same contained fetch without --connect first. On Linux that half catches something specific: a network namespace that silently failed to be created would leave the sandbox on the machine's own loopback, and the positive result alone would then prove nothing.

  • --connect works on macOS. A contained tool can reach one service already running on your machine -- a browser with remote debugging on, a local database, an emulator -- named one port at a time, the same way as on Windows:
  nvx --connect 9222:19222 npx some-tool --endpoint http://127.0.0.1:19222

It was Windows-only because that is where it was built, and the flag warned and did nothing elsewhere. The need is the same on macOS: in the default proxy mode the Seatbelt profile permits outbound connections to the egress proxy's own ports and nothing else, so a contained tool cannot reach your database either.

macOS could have taken a shortcut. The sandbox shares the host's loopback there, so permitting the service's own port in the profile would have worked, with no listener and no second port number. nvx runs the relay anyway and the profile opens only the relay's port. That keeps one meaning for the flag on both platforms -- the same command line, the same two-number rule, the same NVX_CONNECT_<port> -- and keeps the property the feature is for: the contained process chooses when to connect, and nvx chooses to what.

No peer check on macOS, unlike Windows, and that is a measured difference rather than an omission. Windows needs one because every sandbox on a machine shares a package identity and could otherwise reach another's tunnel. On macOS a process outside any sandbox can already open the service itself, so the relay hands it nothing, and another sandbox cannot reach the relay's port because its own profile permits only its own proxy ports.

scripts/sandbox-smoke-macos.sh drives it on CI hardware against a real service, and runs the same contained fetch without --connect first. That order is the point: if macOS ever stopped enforcing the profile's network rules, the fetch would succeed either way and a one-sided test would pass while measuring nothing.

Linux still does not have it, and the warning there now says so plainly instead of calling --connect a Windows feature. Linux is the harder one: its sandbox runs in a loopback-only network namespace, so your services are unreachable at the routing layer, and closing that needs the relay treatment the egress proxy already gets over AF_UNIX.

Removed

  • The wsl, wslc and systemd-nspawn containment providers. All three arrived in one commit that added six backends at once, and none was ever asked for by a design document, exercised by a test, or run by any CI machine. What they carried instead were defects: none of them received the network context, so isolation.network.mode: offline was accepted and silently ignored under all three, and nspawn additionally required root and bind-mounted the project writable, leaving root-owned files behind that a later install as yourself could not replace.

native and docker remain, plus sandbox-exec on macOS. Naming a removed provider in a policy or on --filesystem-provider is an unknown provider: the run stops rather than falling back to something else. Measured across all seven retired names, including with NVX_EXPERIMENTAL=1 set.

NVX_EXPERIMENTAL is gone with them, since those three were the only thing it gated. The refusal message now lists the providers that do exist, taken from the registry rather than written out by hand, which is how it came to omit the macOS one.

Added

  • isolation.filesystem.allow_read_exec: let a contained tool reach a program kept outside the project. The sandbox grants the project, a throwaway home and nvx's own runtimes, and nothing else — so a tool whose executables live elsewhere cannot run them.

Playwright is the case that forced it. Its browsers are in %LOCALAPPDATA%\ms-playwright, and a contained process could not list that directory at all: measured EPERM inside against 27 entries outside, and LIST_OK inside once the root was granted.

  { "isolation": { "filesystem": {
      "allow_read_exec": ["%LOCALAPPDATA%/ms-playwright"] } } }

Read and execute only, never write. Paths expand ~, $VAR and %VAR% so one file works across machines; a path that is not present here is skipped with a warning rather than failing the run. Adding one counts as loosening, so a checked-in project file needs the same approval an egress allowlist entry does. On Windows the grant goes to the project's own capability rather than the shared package identity — these ACEs persist on disk, so granting the shared identity would have admitted every sandbox on the machine rather than only this project's.

The grant is recorded, and withdrawn when the policy stops asking for it. It persists between runs by design -- re-applying it every launch would put a permissions call on the startup path for every root -- so nvx keeps a ledger of what it granted and reconciles it on each contained run in that project. Delete the entry, or the whole policy file, and the next run takes the permission off disk. nvx grants list shows them; nvx grants reset withdraws them, instead of deleting its own records and orphaning the permissions they tracked, which is what it did before. A record it cannot read is kept rather than deleted, and reported, since removing it would strand exactly what it was there to track.

This also corrects the MCP containment design, which recorded that browser-driving servers cannot be contained on Windows because connections *into* an AppContainer are refused. True when reaching a browser already running on the host — but when Playwright launches its own, the browser is a child inside the container and is reached over intra-container loopback, which nvx already proves works. Ports were never the blocker for that case; the binary being unreachable was.

Linux grants reading and executing, not listing. A contained process can read and run files under a granted root but cannot readdir it. That is not specific to this feature: /usr/bin and /etc cannot be listed either, and they have carried the directory-read right since the Linux sandbox was written. Recorded in README rather than worked around.

  • --connect (Windows): let a contained tool reach one service already running on your machine. The mirror of --expose, and the missing direction. The sandbox has no route to your loopback — Windows refuses an AppContainer's loopback connections, and the egress proxy declines host loopback destinations on purpose — so a contained tool that must talk to a browser with remote debugging on, a local database or a device emulator had no way to get there.
  nvx --connect 9222:19222 npx some-tool --endpoint http://127.0.0.1:19222

nvx runs a listener inside the sandbox and dials 127.0.0.1:9222 itself from outside. The contained side chooses when to connect, never where. Both ends close when the command exits.

The two numbers must differ, for the same measured reason --expose requires it: an AppContainer shares the host's network stack rather than getting its own, so one port cannot hold both the in-sandbox listener and the real service. Omit the second (--connect 9222) and nvx picks a free port, prints it, and sets NVX_CONNECT_9222 in the sandbox — useful for a tool that reads its endpoint from the environment, not for a command line your shell expands before nvx runs.

In a policy file it is isolation.network.connect_ports; adding one counts as loosening, so a project cannot grant itself a host port without approval. This is deliberately not the machine-wide loopback exemption removed in 0.5.0, which opened every service on 127.0.0.1 to every sandbox permanently and needed elevation to revoke — --connect grants nothing at the OS level at all.

On macOS and Linux the flag parses and warns that it does nothing, rather than being silently ignored. (--expose now warns there too; it was silent before.) Both warn when the command is not sandboxed at all, for the same reason.

  • A permission nvx granted that later widened is left in place, and said so accurately. nvx grants read/execute on a directory; a later run in the same project uses that directory as its working directory, so nvx's own writable-root grant replaces its own entry with a wider one. Dropping the policy entry then reported "it is not the one nvx granted", which was false twice over — nvx had granted both. It now says the permission is wider than the one recorded and explains that removing it would take away more than the policy granted.
  • nvx grants reset no longer reports withdrawing permissions that were not there. A record naming a path with no permission on it counted as a withdrawal, so the command claimed to have removed something it had not.
  • nvx grants list no longer rewrites anything. Asking what is recorded renamed a record it could not parse, as a side effect of a read-only query.
  • A containment probe could silently skip itself while the gate reported success. Staging the test binary as the contained child fails intermittently with "The handle is invalid", and the helper skipped on the first failure — so a run could report "0 failures" with cross-session isolation, or the deny-ACE check, never having executed. Both happened, on two separate acceptance passes, each time a different test. The read is retried now, and the skip message says outright that a containment assertion is not being checked.
  • The pre-0.5.0 legacy-grant weakness is closed, and the documents that still described it as live are corrected. Up to 0.5.0 every sandbox ran as one shared identity, so the permissions nvx left on a project were satisfied by a sandbox running in any other project. Per-project AppContainer packages ended that: nothing holds the shared identity any more. Measured 2026-08-31 by recreating the exact scenario the enforcement matrix describes — the real shared package SID granted (OI)(CI)(M) on a directory, then a contained process from an unrelated project run against it: EPERM on both write and list. The matrix cell and README's limitation said "still writable by every sandbox on the machine" for two days after that stopped being true.
  • nvx no longer deletes AppContainer permissions that are not its own. When clearing legacy grants it removed *every* AppContainer package ACE on the working directory and logged each as "left on … by an earlier nvx" — a false statement about a permission it had just deleted, if the entry belonged to another sandboxing tool. The widening was argued as safe because "in practice these are nvx's own", which is now checkable rather than assumed: nvx's package names are enumerable, so it identifies its own and leaves anything else alone, reporting what it found.
  • A failed contained install ends with nvx's advice, not npm's. nvx explains the stranded-setup problem before the command runs, and then npm prints twenty-odd lines ending with "try running the command again as root/Administrator" — which is not the fix. The explanation is repeated after a failed package-manager run, so the correct remedy is the last thing on screen.
  • Logs rescued from failed runs are now reclaimed. When a contained run fails, nvx copies npm's debug log out of the guest home before deleting it, so the path the error points at still exists. Nothing ever removed those copies — guest homes have a sweep and package profiles have a sweep, and these did not, so they accumulated for the life of the installation. Measured on the development machine: 3,146 folders, 181 MB, and nvx cleanup left every one. They are swept after 14 days, automatically after a command and in full on nvx cleanup.
  • The Windows release gate now runs under -race, and a data race it could never have seen is fixed. CI's unit step used -race but not NVX_PROBE; CI's probe step used NVX_PROBE but not -race; and CONTRIBUTING's manual gate matched the latter. The two were never combined, so no gate could observe a race in a probe test — and one was there: TestExposedPortIsReachableFromTheHost shared a strings.Builder between os/exec's copier goroutines and its own poll loop. Found by an acceptance pass running both flags together, one commit after a sweep titled "Fix the race CI caught" missed it.
  • scripts/bench.py no longer crashes in the case its own docstring claimed to have fixed. It preferred nvx.exe on Windows but fell back to nvx — and this repo's tree carries a gitignored macOS build under that name, so the fallback handed Windows a Mach-O file and it died with the same unhandled OSError: [WinError 193] the docstring described as gone. Preferring the right *name* is not the same as checking the file runs here; it now checks.
  • Stalled permission writes no longer accumulate for the life of the process. Writing an ACL on the user profile root can block indefinitely behind the OneDrive and Defender filter drivers, so nvx bounds each write with a deadline and abandons one that overruns — a blocked syscall cannot be cancelled. The reasoning for that was "the ancestor walk's own budget bounds how many can be outstanding", which is true of one walk and false of a process that performs hundreds, because each abandoned goroutine pins an OS thread.

An acceptance pass measured the consequence where nvx is long-lived — the release-gate test binary. A run that died with runtime: SetWaitableTimer failed; errno= 5 had 49 of 83 goroutines blocked in that write, all from the ancestor walk, 34 of them for over a minute. The same binary separately failed a containment test with CreateProcess(AppContainer) ... The handle is invalid, and the gate failed two runs in four. Both are what thread and handle exhaustion look like.

Two per-process bounds now: a path whose write has already stalled is not attempted again, and there is a hard ceiling on outstanding abandoned writes. Both make the grant *less* likely to be applied, which is the right direction — these ancestor grants are already best-effort and already skipped for speed, and a process that stays alive is worth more than one of them.

  • nvx doctor no longer offers a PATH repair for problems that are not the PATH. On a machine with a healthy PATH and a stale nvx setup grant it printed "[OK] shim dir is on PATH" and then, three lines later, told the user to repair their PATH with nvx doctor --fix — which regenerates shims and cannot touch a grant needing an Administrator terminal. Following it changed the user's PATH and left the report red.
  • nvx policy init rejects unknown flags. nvx policy init --nope wrote the file and exited 0. The flags decide *where* a security policy is written, so ignoring one silently writes it somewhere the user did not ask for and reports success.
  • The Windows dispatch-overhead figure is published as a range. A fourth machine measured 0.9–8.6 ms, below the "9–57 ms" floor stated a commit earlier — which was itself a correction of a flat "~38 ms". Samples now span 0.9 to 57 ms across several machines and both documents quote the range.
  • Removed windowsSandboxSetupDone. It answered "has setup run" by testing for a loopback exemption — a state setup no longer creates and actively removes — so it could only return false. Nothing called it.
  • PRODUCT.md records that its "No elevation" constraint is currently violated on Windows, for npx only. Contained npx needs nvx setup; node, npm install and npm run do not. It fails closed rather than running uncontained, so no security guarantee is weakened — the constraint's second sentence holds while its first does not. Written down rather than reworded to match the code, because a constraint edited to fit the implementation stops being a constraint. Three unelevated fixes were tried and measured to fail.
  • The "why npx failed" explanation no longer goes silent after one run. Its once-per-machine marker meant the first affected run anywhere consumed it and every project afterwards got npm's raw EPERM with nothing from nvx — including brand-new projects, in the release whose commit was titled "Say why npx fails after an upgrade". The stranded-setup case now repeats until nvx setup is re-run, which is what clears it; the ordinary "you never ran setup" advisory is still shown once.
  • SECURITY.md still described a containment weakness that measurement disproves. It said a contained process can list "your home directory, C:\Users and C:\". Only the home directory is listable; the other two need an elevated grant. README and the enforcement matrix were corrected for this and this file was missed — a partial sweep, which is how the same wrong sentence survives in one place after being fixed in two.
  • nvx import asks before downloading. With no arguments it went straight to installing every version found across nvm, fnm and volta — three full runtimes on the machine that caught it — from a command whose name suggests reading. It now lists what it found and asks; -y approves.
  • nvx grants list no longer presents a pin whose file is gone as if the file were there. The record is kept deliberately (the pin is a content hash, so an unchanged file returning is still trusted) but the line now says the file is absent. Annotated rather than removed: list answers a question and must not rewrite anything to do it.
  • A warning about an untrusted project policy printed twice per contained run. A contained command loads the policy twice — once to decide whether to sandbox, once inside the sandbox launch — so one problem was reported as two. Reported by an acceptance pass, dismissed after measuring the *uncontained* case (where it correctly prints once), and confirmed on re-measurement.
  • Windows now fails closed if the writable-roots declaration and the sandbox disagree. sandboxWritableRoots is where nvx declares what a contained process may write; Seatbelt and Landlock read it, and Windows did not — it granted the same pair from its own code. An acceptance pass proved the drift was live by widening the declaration to include the working directory's *parent*: the unit tests went red and the real Windows containment probe stayed green. Windows now reads the declaration and refuses to launch, naming the path, if it lists a root the AppContainer path does not implement. The same sabotage now stops the launch.
  • README described a containment weakness that is narrower than stated. It said a contained process can list "your home directory, C:\Users and C:\", attributing all three to an ACE Windows ships. Measured in a real container: the home directory is listable (that ACE is real and nvx cannot revoke it), and C:\ and C:\Users are not — they carry no such entry and are readable only where an elevated nvx setup has granted them. The entry overstated the weakness, which is the safe direction to be wrong in and still wrong.
  • README named a version that does not exist. Two limitations described behaviour as shipping in "0.5.8" while appVersion is 0.5.7, the latest tag is v0.5.7, and the work sits under [Unreleased]. They now say "the next release", so nothing published names a version that never was.
  • nvx import <unknown-source> no longer exits 0. nvx import bogus printed "No previous Node.js installations found for source 'bogus'." and reported success — so a typo read as "that version manager had nothing installed", which nvx had never checked, because no scanner matched the name. Unknown sources are now named and rejected with exit 1.

Its messages were misleading in the same direction. import reads which *versions* another manager has and installs those versions itself, downloading and checksum-verifying each from nodejs.org; nothing is copied out of the other manager. It said "Importing Node.js v22.11.0 from nvm-windows", which reads as a copy from a source nvx never opened. It now says what it is doing.

  • scripts/bench.py can be run the way README says to run it. Its --nvx default was ./nvx on every platform, so python scripts/bench.py on Windows — the exact command README gives — failed, either with "nvx binary not found" or, in a tree that also holds a macOS build named nvx, an unhandled OSError as Windows refused to execute a Mach-O file. It picks the right name per platform now, and says how to build one when there is none.
  • PRODUCT.md stated Windows dispatch overhead as a constant. It said "~38 ms Windows" flatly; measured with the project's own tool it is 9 ms, 38 ms and 57 ms on three machines. It is the one of the three platform figures that moves, and it now says so.
  • Upgrading requires re-running nvx setup on Windows, if you ever ran it. Per-project sandbox identities (below) mean the drive-root grants an earlier nvx setup made now name an identity nothing launches under, so they stop applying. The visible symptom is npx: it fails with EPERM: operation not permitted, lstat 'C:\Users' out of npm's own dependency walker, which stats every ancestor up to the drive root. npm install, npm run and node do not make that walk and are unaffected.

Found by an acceptance pass, which measured the same command succeeding on 0.5.7 and failing on this build. nvx said nothing at the time — it checked only drive roots, not C:\Users, checked them against the wrong identity, and suppressed the advisory it did have because the machine had seen it once years earlier. All three are fixed: the check now uses the identity nvx setup actually grants, covers every path it grants, and re-arms when that identity changes. nvx doctor reports a stranded setup and exits non-zero.

Worth stating plainly, because the documentation did not: contained npx has always needed nvx setup. The elevated step was described as optional, and for npx it never was.

  • One nvx sandbox could reach another's loopback services, defeating the egress allowlist. Windows permits loopback within an AppContainer package, and every nvx sandbox on a machine shared one. So any port a contained process bound was reachable from every other contained process — a different project, an empty allowlist, no --connect, no --expose, no loopback exemption. An acceptance pass used it to complete a TLS exchange with a host the calling project had never allowlisted, by relaying through a second sandbox.

Measured with both controls, which is what makes it specific: a true host process could not reach a sandbox's listener, and a sandbox could not reach a listener on the host — only sandbox-to-sandbox worked.

nvx now gives each project its own AppContainer package. Cross-project connections are refused; two runs of the *same* project still reach each other, which is one trust domain and is documented in SECURITY.md rather than claimed away. nvx setup's elevated drive-root grant moved from the package to a capability every launch carries, because per-project packages cannot be named in advance by a command that runs once; --undo revokes both, so an older setup is still undone.

The profiles this registers are reclaimed automatically, after a contained command, a few at a time — the same terms as the guest-home sweep, which exists because a command nobody runs cleans nothing up. A profile is kept while any live session holds it, and for a week after its last use so that working in a project does not re-register its profile on every run. nvx cleanup does the same sweep without the per-run limit.

scripts/sandbox-enforcement-windows.ps1 asserts it end to end now — the cross-project connection must be refused and the same-project one must succeed, so a sandbox that refuses everything cannot pass.

  • Three places said a contained process cannot stream a child's output. It can. docs/enforcement-matrix.md said async spawn(..., {stdio:"pipe"}) "still hangs"; SECURITY.md headed the bullet "a contained process cannot capture a child's output" and then bolded "streaming capture is not" four lines before explaining that it is; and the two-minute hint a user sees when an install is slow named esbuild as a package that "blocks forever". All three were fixed weeks ago and README said so. Measured 2026-08-29 inside a real AppContainer: spawn with piped stdio returned its child's output and exit code. This matters most in the matrix, which PRODUCT.md names as the authority, and in the hint, which is the one of the three a user meets at the worst moment. The hint no longer asserts a cause at all — it reports the symptom, names the one restriction that is still real (writing to a child's stdin), and offers --no-sandbox. Its test asserted the old wording, so it would have held the stale claim in place; it now asserts what stays true.
  • scripts/bench.py reported a negative overhead. Run exactly as README.md documents, it printed => nvx dispatch overhead : -50.4 ms. It took its baseline from shutil.which("node"), which on any machine with nvx installed is the nvx shim — so it measured nvx against itself and subtracted. It now asks the binary where it actually lives and says so when PATH gave it a shim. This is the same defect swept out of the shell scripts one release earlier; that sweep globbed *.ps1 and *.sh and missed the one .py file in the same directory.
  • nvx audit no longer shows the reader raw %s and %d. The log stores each warning's format string and never the rendered text — deliberately, since rendering once wrote a live password into it — but that meant audit output read like a formatting bug rather than a redaction. Withheld values now render as […]. Applied when reading, so the stored bytes keep their aggregation key and records already on disk read correctly too.
  • nvx doctor --fix printed a mangled path. %q escapes every backslash, so one line reported "C:\\Users\\..." while every other path in the same output was clean.
  • nvx doctor now diagnoses a policy file it cannot read. When a policy will not load nvx refuses to run, and the refusal an MCP client receives says "Check it with nvx doctor" — but doctor looked at PATH and shim interception and nothing else, so it reported everything healthy and exited 0 with a broken .nvx-policy.json in the working directory. The path and the parse error existed only on stderr, which is the stream an MCP client discards, so the one thing the reader needed was in the one place they could not see. Doctor is the right place for it: it still works when everything else refuses, because loading a policy is not on its path. It now names the file and the parse error and exits non-zero.
  • scripts/sandbox-smoke-egress.ps1 got the two fixes its siblings got. It still exited 1 under Windows PowerShell 5.1, still ran init-shims against the developer's real ~/.nvx, still tried to overwrite the installed nvx.exe, and still left ~/nvx-egress-smoke behind — the earlier fix was applied to one script and not swept across the rest. It now uses a throwaway NVX_HOME and cleans up after itself. Its "an allowlisted host is reachable" half also no longer skips on any machine whose node predates 24: it installs the runtime it needs instead of probing PATH for one. scripts/sandbox-smoke-macos.sh had the same real-~/.nvx problem and is fixed with it.
  • npm run no longer warns that commands may be bypassing nvx when they are not. Every npm run printed "A runtime dir is ahead of nvx's shim dir on PATH; some commands may bypass nvx. Run: nvx doctor" — and nvx doctor, run immediately after, reported the PATH healthy. npm puts <runtime>/node_modules/npm/node_modules/@npmcli/run-script/lib/node-gyp-bin on the child's PATH ahead of the shim dir (measured at index 7 against the shim dir's 61), and anything inside a runtime tree counted as shadowing. That directory holds node-gyp and nothing else, so it cannot shadow a command nvx wraps. The check now asks what a directory actually contains, which is the question "is it under a runtime root" was standing in for.
  • scripts/sandbox-smoke.ps1 no longer runs under the default Windows shell and no longer edits the developer's nvx install. Two defects in the script CONTRIBUTING tells a maintainer to run by hand:

It exited 1 under Windows PowerShell 5.1 while passing under pwsh 7, which is what CI pins — $ErrorActionPreference = 'Stop' plus a native command's stderr redirection, the same trap fixed in its sibling. A maintainer following the documented gate got a red result that was not a product failure.

And it worked against the real ~/.nvx: it ran init-shims there, overwriting the installed shims, tried to overwrite the installed nvx.exe (failing only because the file was in use), and mirrored a Node distribution into the real versions directory by resolving node through PATH. On a machine with nvx installed, node *is* the nvx shim — so it copied ~/.nvx/bin, nvx.exe included, to ~/.nvx/versions/node/v, which then appeared in nvx list as an installed version. It also left ~/nvx-smoke-wd behind on every run. It now uses a throwaway NVX_HOME, takes its runtime from nvx rather than from PATH, and removes everything it created.

  • CONTRIBUTING's Windows release gate no longer fails on a clean checkout. It said to expect "0 failures and exactly these 4 top-level skips… 337 passing", and warned that a fifth "means something is quietly not being checked". An unelevated run — the normal way to run it, since nvx is built not to need elevation — produces five. The fifth needs write access to the DACL on C:\WINDOWS\System32\cmd.exe, which an unelevated account never has. Both numbers were also a day stale. Re-measured 2026-08-29, unelevated: 392 passing, 5 skipping, 0 failing, that run taking 724s. Each skip is now named, so a mismatch says which one rather than only how many. CONTRIBUTING carries the current counts and a duration range rather than a single figure — repeated runs on this machine span 535s to 724s, so quoting one of them as *the* duration is what made these two documents look like they disagreed.
  • nvx init-shims names the directory it wrote to. It printed ~/.nvx/bin whatever NVX_HOME was set to, so anyone running with it set — the Windows enforcement script does, every run — was told the shims had gone somewhere they had not.
  • nvx doctor no longer reports a check it did not make. The healthy line read shim dir is first on PATH (position 53), which contradicts itself. Being first is not the test: what is checked is that no nvx raw-runtime directory sits ahead of the shim dir, and position does not enter into it. The line now says that. The verdict was right all along; the explanation was not, which is worse than useless to someone diagnosing a PATH problem.
  • Two timing figures in the README could not both be true, and one did not reproduce. The steady-state contained run was given as ~390ms "of which ~210ms is Node's own startup", leaving ~180ms for nvx — against ~370ms quoted for nvx's own setup in the next bullet. Re-measured 2026-08-29 on a second Windows 11 machine: 2.9s first contained run, 785ms steady (median of 8), 58ms for the same Node binary run directly, 92ms for the same command uncontained. The first-run cost reproduced; the steady state is about twice the published figure and Node's own startup about a quarter of it. Both claims are replaced with measurements, and the decomposition that created the contradiction is gone rather than re-guessed.
  • Three refusals reached an MCP client as a silently closed pipe — a project policy file that cannot be parsed, a policy that would not load, and a global install that cannot be contained. All three sit before the verification step that reports refusals, so none was reported. The advice for an unreadable policy was also unreachable: its reason contains the words "security policy", so it matched the policy branch first and told people to edit a policy nvx could not read.

The first of those was still silent after the other two were fixed, and an acceptance pass caught it. Two code paths can meet an unreadable policy — the trust check parses every project policy file before anything else, and building the effective policy parses them again — and only the second reported. The first is the one a person actually reaches, because it runs earlier: a hand-edited .nvx-policy.json with a brace missing, or the byte-order mark fixed below. Both paths now go through one function, and the test drives a refused run rather than the reporter, which is what the five existing tests did while this went unnoticed.

  • nvx no longer withdraws a filesystem permission it did not grant. A directory that is both the sandbox's writable root and named in allow_read_exec was recorded as a read/execute grant, even though nvx had skipped granting over the broader write permission already there. nvx grants reset then removed it: measured, the sandbox's write access to the user's own project was deleted while nvx reported withdrawing a read/execute permission. Withdrawing takes an identity's whole entry, not one right from it.

Two guards now. Only a permission that is, or is about to be, nvx's own is recorded — decided before the record is written, since the record has to be written first. And a withdrawal refuses to touch an entry that is not nvx's, drops the record instead, and says so — which also repairs records the previous build already wrote.

Containment was never weakened by this; the damage was to access nvx itself had granted.

  • The advice nvx gives an MCP client now matches the refusal. One fixed remedy was sent for every reason, telling people to set NVX_YES=true for three that are policy decisions rather than warnings, where it has no prompt to approve and cannot help.
  • An MCP server that nvx refuses to start now says why, instead of looking like a crash. A server spawned by an editor talks JSON-RPC over its pipes, and nvx wrote its refusal to standard error and exited — so the client saw a process that closed without answering and reported -32000: Connection closed, the same message an unrelated transport bug produces. That misdiagnosis happened in practice: a package published 7.3 hours earlier tripped the release-age window and the failure was first attributed to a known connection bug. It also clears itself after 24 hours, so the server starts working again without anyone learning what happened.

On the refusal path only, nvx now answers the request the client has already sent with a JSON-RPC error naming the reason, the package, and what to do about it — set NVX_YES=true for that server, or pin the version. It never reads that input on a path that goes on to launch the real server, replies only when the pending input is genuinely a JSON-RPC request, and waits no more than two seconds for one.

Several abort messages said "aborted by user" when nobody had been asked; they now say the warning was not approved, which is what happened.

Added

  • NVX_DEBUG=1 and nvx report: keep what nvx said, so a problem can be looked at afterwards. audit.log records 16 kinds of event; everything else nvx prints went to the terminal and was gone when it scrolled. A run that warned about a removed environment variable, or refused an install, left no trace — so the only way to find out what happened was to reproduce it while watching. For anything running unattended, that is not available, which is exactly when the question gets asked.

NVX_DEBUG=1 records everything nvx prints to ~/.nvx/debug.log. Off by default, like NVX_TRACE. It rotates once at 5 MB, so a machine left with it set cannot fill its disk.

nvx report collects the version, whether the shims are intercepting, the policy in effect and the tails of both logs into one file — the four things someone else needs before they can help. Nothing is uploaded: nvx has no uploader and this does not add one.

Unlike audit.log, the capture holds rendered text, so it can contain paths, hostnames and package names. LogWarn still records format strings only and audit.log is unchanged — the invariant that keeps a password in a URL out of it still holds. The capture strips credentials from URLs in the recorded command line, which is a mitigation rather than a guarantee; the file says so in its own header, and nvx report says so before handing the file over.

  • isolation.environment.allow: name an environment variable a contained command needs. Containment keeps 11 environment variables on Windows (7 elsewhere) and drops everything else, so an install script cannot read the secrets in the shell that launched it. That is the point of it, and it stays.

The cost is that a variable a build genuinely needs goes with them. Measured on Windows: 107 variables outside a contained run, 48 inside, with CI and NODE_ENV among the casualties. Until now the only way to get one through was --no-sandbox — answering "my build needs NODE_ENV" by switching the sandbox off.

  { "isolation": { "environment": { "allow": ["CI", "NODE_ENV"] } } }

Exact names, case-insensitive, no patterns. A name matching a sensitive prefix (AWS_, GITHUB_, SECRET_, …) is refused and reported rather than honoured: a policy file lives in the repository, so one line in one must not be able to hand a cloud credential to whatever an install script runs. Adding an entry counts as loosening, so a project-local file naming one needs the same approval an egress host does.

Known issues

  • Bun needs 1.4.x inside the Windows sandbox; older Bun fails. Measured 2026-09-06: Bun 1.4.2 runs contained correctly — bun install, bunx and relative-path reads and writes all work. Bun 1.3.1 fails every relative-path operation with EBADFD, and without nvx setup cannot start a script at all.

Older Bun keeps a working-directory descriptor captured at startup that an AppContainer will not honour, so absolute paths work and relative ones do not. Node is unaffected because it holds no such descriptor. Bun added AppContainer support in oven-sh/bun#33119, merged 2026-07-20 and shipped from 1.4.0.

This was documented here on 2026-09-05 as "Bun does not work inside the Windows sandbox at all", from measurements against 1.3.1 alone. The mechanism described was right; the scope was not, and the fix already existed upstream.

Fixed

  • The installer's PATH update is now tested. That single write had already shipped one defect and had no coverage, because the logic sat inline in a script that installs software when you run it. It is now a function the installer calls, install.ps1 -LibraryOnly defines it without installing anything, and a Windows CI step exercises it against a scratch registry key: an expandable PATH keeps its type and its variables, a plain one is not converted, and running it twice does not add the directory twice.
  • The Windows installer no longer flattens %VAR% entries in your PATH, or changes its type. install.ps1 read the User PATH with [Environment]::GetEnvironmentVariable, which *expands* a REG_EXPAND_SZ value, and wrote it back with SetEnvironmentVariable, which always writes REG_SZ. So installing nvx on a machine whose PATH contained %USERPROFILE%\bin replaced it with today's expansion of that path and converted the value's type, both permanently. Measured against a scratch key: the expanding read turns %USERPROFILE%\bin;C:\Windows into C:\Users\<you>\bin;C:\Windows. The installer now reads the raw value, writes it back with the type it found, and sends the change notification the .NET setter used to send.
  • nvx doctor --fix no longer changes the type of your User PATH. Windows stores that value as REG_EXPAND_SZ, which is what makes an entry written as %USERPROFILE%\bin or %JAVA_HOME%\bin resolve — the value is expanded when it is read. The repair wrote it back through [Environment]::SetEnvironmentVariable, which always writes REG_SZ, so it converted the type on every machine it ran on and any such entry silently stopped resolving. That is a repair breaking PATH entries while reporting that it had repaired PATH. The value is now written directly to the registry with the type it already had, in either direction, and the notification that tells running programs the environment moved is sent as before.

A machine already converted stays as it is: the repair preserves what it finds, it does not guess that a REG_SZ PATH was meant to be expandable.

  • Bun could not run inside the Linux sandbox. bun --version worked, and everything real did not: bun script.js aborted, and bun install failed with "JSON document is too deeply nested" and "StackOverflow" against a 65-byte package.json that parses fine outside. Bun reads /proc/self to size its stack, and every read under /proc inside the sandbox was refused, because the Landlock ruleset granted nothing there. Node never reads it, which is why only Bun was affected and why this went unnoticed.

The sandbox now gets a /proc of its own rather than the grant alone. Nothing had remounted it, so the one visible inside was the host's, listing every process on the machine — cmdline for all of them, environ for the user's own, which is where credentials live. Granting that would have been worse than the bug. Instead the supervisor takes a private mount namespace and mounts a fresh procfs, and since it is already PID 1 of its own PID namespace, what a contained process sees is itself and its children: measured at two entries, with a planted host process invisible. If that mount fails, the grant is withheld and the run says so.

  • A contained process could not find the other runtime. nvx put the launched runtime's directory on the contained PATH, so a script run by Bun that called node fell through to the machine's own Node — on Windows, to C:\Program Files odejs ode.exe, which the container then refused — and a script run by Node could not resolve bun at all. A postinstall calling the other runtime is ordinary. Both runtimes nvx manages are now on the contained PATH, the launched one first.
  • Inside the sandbox on Linux and macOS, a nested node lookup did not get the runtime nvx pinned. npm on those platforms is a script that resolves node through PATH. Inside the sandbox that PATH leads with nvx's shim directory, the arrangement nvx env and init-shims produce, so npm found the node shim, and the shim could not resolve a version from in there, where NVX_HOME is scrubbed and HOME is the throwaway guest profile. It then fell back to any non-nvx node it could see, and the two platforms failed differently:
  • macOS ran the wrong runtime, silently. Measured on a runner: the contained process was on the pinned v22.23.2 while a nested lookup got the machine's own v24.20.0. The install succeeded, under a runtime nobody chose.
  • Linux failed outright, because its sandbox only permits execution from an allowlist that a stray node is usually outside of: "Could not find real executable for node", and no install. Where a permitted one does exist, Linux is silent about it too, measured as pinned v22.23.2 against a nested v20.20.2.

A session that had run nvx use was unaffected either way, which is why this went unseen. The pinned runtime's bin directory now leads the contained PATH, which is the right order inside a sandbox: a nested node or npm should be the pinned runtime running inside the containment already active, not a shim trying to start a second one. Windows was never affected, since npm.cmd resolves node.exe next to itself. Both platforms' smoke tests now install a package through the sandbox and check that a nested lookup gets the pinned version.

  • The Docker provider could not write to your project on Linux. The container drops every capability, which is right, but it also ran as root, which is not: root without CAP_DAC_OVERRIDE has no privilege over files owned by you, so a project directory could not be entered at 0700 and could not be written at 0755. Under npm install that is every write the install makes. The container now runs as the invoking user on Linux, which also keeps what it writes owned by you rather than by root. macOS and Windows are unaffected and unchanged: Docker Desktop presents the mount through a shim that synthesises ownership, which is why this was invisible on a Windows machine and stayed invisible while the provider had no test that ran it.

npm install then failed for a second reason found by fixing the first: the environment is scrubbed, so the container had no HOME, npm resolved its cache to the filesystem root, and a container no longer running as root could not create it. The container now gets HOME=/tmp, the tmpfs nvx already mounts — writable whatever user it runs as, and discarded with the container, like the throwaway home the native providers give a contained process. The smoke test installs a real package and checks the files belong to you.

  • Installing from a local path or a git URL no longer fails as an unknown package. npm install ./vendor/thing.tgz, ../sibling, file:../lib and github:user/repo are ordinary npm specs and none of them names a registry package, but nvx asked the registry for each one, got a 404, and asked whether to proceed without metadata checks -- a question that denies when there is no terminal, so the install failed under an agent or in CI, blaming registry metadata for something that was never in a registry. Those specs are now recognised, and the run says which checks do not apply to them. A registry name is checked exactly as before.
  • A sandboxed process on macOS no longer outlives an nvx that was told to stop. macOS has no kill-on-parent-death primitive -- Windows uses a job object, Linux a PID namespace -- and nvx installed no signal handler at all, so kill <nvx> left the contained process running, holding its port or its work. Interrupt and terminate are now passed to the child, and terminate is followed by a kill if it has not exited within five seconds. kill -9 and the child's own grandchildren remain outside what this can cover.
  • Another tool's policy.json is no longer read as an nvx policy. nvx accepts .nvx-policy.json and, as a convenience, a bare policy.json, and it searches every directory above the project. That bare name belongs to several other tools -- Open Policy Agent bundles, IAM exports, Terraform -- so one sitting anywhere above a project produced a trust prompt for a file nobody wrote for nvx, warnings that its keys were misspelt nvx settings, and a pinned hash that broke whenever the other tool rewrote it. A bare policy.json now counts only if it carries at least one setting nvx knows; the explicit .nvx-policy.json is always read.
  • A cached Bun release list stops standing in for the real one after 30 days. When GitHub could not be reached, any cache was accepted at any age, so a machine off the network for months resolved bun latest to whatever was newest back then and said only that a fetch had failed. Past the bound it now fails and says how old the list is; inside it, the fallback warning states the age too. Installing an exact version offline is unaffected -- that path never consults this list.
  • A Node version that cannot be migrated to the current layout is reported. Versions installed by an older nvx live in ~/.nvx/versions/<v> and are moved under versions/node on startup. The move's error was discarded, so a version that could not be moved -- a leftover directory of the same name, a file held open, a permission problem -- stayed where nothing looks for it, missing from nvx list with nothing to say why.
  • Leaving a project takes its shims off PATH. Each project gets its own shim directory under ~/.nvx/project-bin, put at the front of PATH on entering the project. Stale entries for the other per-project directory, the npm prefix, were stripped on every switch; these were not, so after a cd from project A into project B, A's shims stayed on PATH behind B's and a command A's node_modules provided kept running in B, from A.
  • lts/* and lts/<codename> now resolve. They are canonical .nvmrc contents and nvx accepted neither: lts/* was rejected as "not a version number" and nvx install lts/hydrogen found no release, while lts alone worked. Both now resolve against the release list and against what is installed, using the codename each install records.
  • nvx use reports failure when the shell did not change. Run without the shell integration, it printed an environment nothing would evaluate, warned that the shell was unchanged, and exited 0, so nvx use 22 && npm test ran on whatever runtime was already there. It now exits 1 in that case; through the integration, which always passes --shell, the switch is evaluated and the exit is 0 as before.
  • The bash integration quotes the nvx path for bash. It used Go's %q, which leaves $ for the shell to expand inside double quotes. Measured through a real bash: a path holding $HOME ran a path that did not exist, and every nvx use and every cd hook failed with it. The path is now a single-quoted POSIX string, the same quoting the PATH assignments already used.
  • --shell=<something nvx does not know> is an error. Every emitter's default branch is PowerShell, so --shell=fish printed PowerShell assignments for fish to evaluate. The four shells nvx can emit for are the only values accepted, case-insensitively.
  • nvx doctor --fix says which PATH entries it removes. Dropping the raw runtime directories that shadow the shims is the repair; a User PATH shorter by several entries with no word about what went was the defect. Each removed entry is now named, in the report and when applying.
  • A runtime archive could write outside its destination through a chain of symlinks. The tar extractor checked each symlink's target lexically, against the directory of the entry's own path. That is right for one link and wrong once the path to an entry passes through links created by earlier entries: link → sub, sub/up → .., then link/up/out → .. resolves inside lexically and to the destination's parent in the filesystem, and a file entry beneath it lands there. Measured on Linux: every individual target passed the old check and the file was written outside. Every entry is now placed by its real path, resolving earlier symlinks component by component and refusing the moment any step leaves the destination, and a symlink's target is walked the same way from its real parent. The shapes real archives use, such as bin/npm → ../lib/node_modules/npm/bin/npm-cli.js, still extract. This needs a compromised or substituted release archive to matter, which is the situation the extraction exists to survive.
  • What is installed is now the bytes that were verified. Both installers hashed the downloaded archive at its path and then extracted from that path: two opens, with whatever the file held at the second one installed under the first one's checksum. Another nvx installing the same version into the same fixed download name is the ordinary way the file changes in between. Measured: with the archive rewritten between the two steps, the rewritten content was extracted. The archive is now read once, those bytes are verified, and those same bytes are extracted, so there is nothing to race. That holds the archive in memory during an install, 25 to 60 MB for a runtime.
  • A large download on a slow connection no longer fails partway through. The HTTP client had a single 60-second timeout covering the whole request, body included, so a 25 to 60 MB archive failed below roughly 4 to 8 Mbps while making steady progress. Connecting, the TLS handshake and waiting for headers are each bounded; the body is bounded only by whether bytes are still arriving, and a download that goes 60 seconds without any is abandoned as stalled. Measured: a body that stopped after 4 KiB was abandoned in under a second with the period shortened, where before it sat out the full minute.
  • Windows: nvx setup --undo could appear to hang. It swept every ancestor path and the profile root through a permission write with no time limit, where every grant nvx makes is bounded, because a filter driver over the profile root can stall such a write indefinitely and one did. On the profile root the write also propagates over the whole tree. Each revoke is now bounded the way each grant is; one that does not finish is reported by path, counted as a failure, and the command exits non-zero with the entries to remove by hand, instead of sitting there.
  • Windows: an argument containing a backslash before a quote reached the contained program changed. The command-line quoting emitted a run of backslashes once before an escaped quote, where the system parser needs each of them doubled. Measured against Windows' own parser: a\"b came back as a\b, and the two- and three-backslash forms were wrong the same way, while eleven other shapes round-tripped. A Windows path inside a quoted JSON argument is the everyday case. The quoting now doubles the run, and a test round-trips every shape through the system parser rather than a hand-written expectation.
  • A version range now resolves to the version npm would install, so the checks run against it. npm install lodash@^4 -- a range, the shape most declared dependencies take -- was an error inside nvx's resolver, the caller turned that into "Could not verify registry metadata ... Proceed without metadata checks?", and -y / NVX_YES approve that prompt by design. So an unattended install of a range skipped the install-script, release-age and OSV checks behind a warning nobody was reading. nvx already had a range parser for engine constraints; the resolver now uses it and picks the highest published version the range allows, which is what npm installs. A typo, a git or URL spec, or a syntax the parser does not know is still an error, and the prompt is still the honest answer there.
  • A destination name outside the hostname grammar is refused before it can reach the egress prompt or the log. The prompt prints the requested host to the terminal, and that host is whatever bytes the sandboxed client put in its SOCKS or CONNECT request. A name carrying a carriage return or a terminal escape can redraw the line the person is reading; a name with an embedded newline can put words in the prompt's mouth. Measured: such names reached the prompt, and with NVX_TRUST_YES set were approved. Both protocol handlers now refuse anything that is not an IP address or an RFC 1123 hostname before resolving it, with the bytes escaped in the warning and the audit entry.
  • A CONNECT request that never ends is dropped, not buffered without limit. The proxy read the request line and each header with no cap, and the client is the sandboxed process while the proxy is nvx itself outside the sandbox. Measured: after 512 KiB with no newline the proxy was still reading. The header phase is now capped at 64 KiB; a request past that is closed, and the tunnel after the headers is not bounded.
  • A project policy's expose_ports now reaches the merged policy. The merge had a branch for every network list except this one, so a project file that set it did nothing -- and the approval gate that already checked it could never fire. It is merged like connect_ports, and an unpinned project file that adds one is ignored until approved.
  • Concurrent nvx processes no longer lose each other's grants. The ledger of policy pins, approved hosts and recorded filesystem permissions was saved atomically but read, modified and written back with nothing serialising the three callers, so two nvx processes on one project -- an npm lifecycle script, a test runner's workers -- could each read the file, add an entry, and the second write discard the first's. A permission with no record is one nothing can withdraw. Every change now goes through one locked read-modify-write, and the save's temp file has a unique name: sixteen concurrent writers in one process collided on a PID-based one.
  • nvx setup --help ran setup. The command scanned its arguments for --undo and --all-drives and ignored everything else, so --help and -h reached the elevation check, and nvx setup --undoo ran setup forward, granting, when the person typing it meant to take the grant back. Setup is the one command that changes ACLs on the machine's drive roots from an Administrator terminal, which is the worst place for "unrecognised means proceed". Measured on the installed build: all three reached the elevation check. --help and -h now print usage and exit 0, anything unrecognised prints usage and exits 2, and nvx help setup works like the other commands.
  • The Docker provider printed environment values in its launch line, and kept them in debug.log. The docker run argument list carries every allowed variable as -e KEY=VALUE, and the launcher logged the list whole. The values are the ones the scrub lets through on purpose: whatever isolation.environment.allow names, which is the mechanism for handing a token to a tool that needs one. So a token a user deliberately allowed into the sandbox appeared on the terminal, in debug.log under NVX_DEBUG=1, and from there in the nvx report bundle people are asked to attach to a bug report. Measured on the installed build with an allowlisted variable holding a sentinel: the sentinel was printed. The line now names each variable and shows <redacted> for its value, in every spelling docker accepts for the flag.
  • Windows: nvx setup ran system tools by name, resolved through PATH, elevated. icacls, reg and CheckNetIsolation were launched as bare names, and PATH is not nvx's: its user half is written by ordinary user-level code and installers, and the shell integration prepends directories to it on every cd. nvx setup runs the same binary as Administrator, so a CheckNetIsolation.exe in a user-writable directory earlier in PATH ran elevated. Measured unelevated with a planted file: it ran and its output was believed. cmd and powershell were reached the same way from the junction and PATH-repair code. Every Windows system tool is now taken from the system directory the kernel reports, never from PATH, and a test refuses any new program launched by a bare name that is not listed with a reason.
  • macOS: the Seatbelt profile was written where a contained process could rewrite it. Both launch paths wrote it to $TMPDIR, which sits under /private/var/folders, one of the roots the profile grants writes on so that contained code has a temp directory. The file was 0600, but a concurrent contained process runs as the same user. Between nvx writing the profile and sandbox-exec reading it, that process could replace the contents with (allow default), and the launch it was racing then ran with no containment. The profile now lives under ~/.nvx/seatbelt, which the profile does not grant writes to. A macOS test drives both launch paths through a stand-in sandbox-exec and checks where the profile actually is; it failed on the runner against the previous code before the fix.
  • npm -- install evil ran uncontained and skipped every pre-install check. Every scan in nvx stopped at --, on the reasoning that the end-of-options separator ends everything nvx has an interest in. That is true of nvx's own flags and wrong for the package manager's command: npm takes its command from the first positional token, and -- ends flag parsing only. Measured against npm 11: npm -- view left-pad version prints the version, npm --dry-run -- install left-pad@1.3.0 plans the install, and bun reads bun -- install as an install. So a verb after -- was invisible to nvx, the command was classified as your own code, and it ran with no sandbox and no typosquat, OSV or release-age check. npm install -- evil was contained but verified nothing, because the package list stopped at the separator too.

The scans now read -- the way the package manager does: before the command it is transparent and the next token is the command; after the command, what follows belongs to the command. After a script-running verb (run, test, start, stop, restart) nothing is nvx's to read, which is what keeps npm test -- install -- measured: the test script runs with install as its argument -- from being read as an install. One ambiguity is resolved toward containment: a positional right after a flag might be the flag's value, so a -- after it is read the cautious way. That affects shapes like npm --silent view -- install and nothing that installs.

  • A project policy could switch on isolated_tools with no approval. The setting moves the npm global prefix to <project>/.nvx/npm_global, and the shell integration puts that prefix on PATH ahead of the runtime and the system on every cd. That is a directory the repository controls, on the user's PATH: a checked-out project could ship its own node, git or npm in it. Project policies are merged with the loosening gate that prompts for an egress host or a passed-through variable, and this setting was the one it never looked at. It is now a loosening like the others, so an unpinned project file that sets it is ignored with the usual warning until approved.
  • Windows: the ninth piped child in a contained process hung, and so did any piped child of a piped child. Two bugs in the streaming-stdio broker with one failure path between them.

nvx pre-creates a pool of named pipes and the preload in each contained node process opens them; a channel went back on the preload's free list when the child using it closed, but nvx served each channel exactly once. So the first child to draw a recycled name -- the ninth, run one after another -- found a dead pipe behind it. Measured: ten sequential children, the first eight streamed and the ninth hung to the deadline. A test runner that spawns a worker per file and waits for each hits this on its ninth file.

Separately, every node process in the sandbox inherits the same channel list and each treated the whole of it as its own. A nested process's first pick was the channel already carrying its own stdout; the open was refused as busy. npm test under most runners -- npm running node running a worker -- is that shape, and it hung.

Both refusals fell through to the raw spawn, which blocks inside libuv before the child exists: the exact hang the broker was built to remove, reached by way of the broker. nvx now serves each channel for the life of the session, putting fresh pipe instances behind a name after each use, and the preload treats a name that will not open as taken and moves to the next one. The pipe itself is the arbiter, so nested processes need no shared bookkeeping. When every name is busy the spawn goes through files, as an empty pool always did; it never goes to the raw call.

The documented limit is unchanged in size and different in shape: 8 piped children streaming at once, now counted across the whole session rather than per process, with no limit on how many run one after another.

  • Linux: a contained process could remove directories from the nvx runtime tree, and could not list any read-only directory. Both came from one mistake. The Landlock access-right constants had an invented WRITE_DIR at bit 3 — the kernel has no such right; bit 3 is READ_DIR — and every right above it was shifted up by one. So the name READ_DIR in the code denoted the kernel's REMOVE_DIR: the read-only mask granted rmdir on /usr, /etc and ~/.nvx/versions, and never granted listing on any of them.

Measured on a 6.18 kernel before the fix: a contained process removed an empty directory under versions/. Nothing else prevents that — the tree is owned by the user, so ordinary permissions allow it, and Landlock was the only thing that could have said no. Afterwards it is refused, and /usr, /etc and the runtime tree can be listed, so a tool that enumerates a directory to find its own binaries now works contained on Linux. The earlier README note recording "cannot be listed" as a Landlock limitation was this bug.

The constants are now pinned against the kernel header's literal values. Every earlier test was written in terms of the same misnamed constants, which is why none of them could see it.

  • Linux: the sandbox refused to start on any kernel between 5.13 and 6.9, blaming a version it did not require. The ruleset asked the kernel to restrict every right through IOCTL_DEV, which arrived in Landlock ABI v5 (Linux 6.10). A kernel that does not know a right refuses the whole ruleset rather than trimming it, so Debian 12 (6.1), RHEL 9 (5.14) and Ubuntu 22.04 (5.15) all failed closed — with an error saying "kernel 5.13+ required", pointing at the wrong thing. CI never saw it because the runner's kernel is new enough to accept the full mask.

nvx now asks the kernel which ABI it speaks and restricts the rights that ABI knows, which is how Landlock is documented to be used across versions. The floor is genuinely 5.13 again. A right a kernel does not offer is simply not restricted on that kernel; the rights added by later ABIs (cross-directory linking, truncation, device ioctls) refine a boundary the original rights already draw, and refusing to run is not more secure than running with what the kernel has. The newer RESOLVE_UNIX right is deliberately never handled: the in-container egress relay connects to a UNIX socket after the sandbox is applied, and handling it would cut every contained process off from the network on kernels new enough to offer it.

  • A contained process no longer inherits whatever handles nvx's caller left open. Windows handle inheritance is all-or-nothing: nvx launched the in-container supervisor with inheritance on and no list restricting it, so the child received every inheritable handle in the nvx process, whatever that happened to be. nvx marks only stdin, stdout and stderr inheritable itself, but the set is not nvx's to control — an inheritable handle held by whoever launched nvx is inherited by nvx and passed straight through the containment boundary.

Measured on Windows 11 with the same launcher before and after: the supervisor inside the container held 26 inherited handles, byte for byte the launching process's set, and afterwards holds 3 — exactly the standard streams. Among the 23 that no longer cross were six pipes and a thread handle belonging to a process outside the container.

This matters more than the handle count suggests, because the caller nvx is built for is an agent harness, and the harness this was measured on does hold extra inheritable pipes. The launch now pins inheritance to an explicit list of the standard handles, so what crosses no longer depends on the caller's hygiene. The list is deduplicated and filtered for unusable entries first: a console gives all three streams the same handle, > log 2>&1 gives stdout and stderr the same handle, and Windows rejects the entire launch for a duplicate or invalid entry rather than skipping it.

  • nvx auto exited 0 after failing to switch. A directory pinned to a version you do not have printed "Run 'nvx install node@22'" and then reported success, so nvx auto && npm test carried on with the wrong runtime. It now exits non-zero when the directory asked for something it could not deliver.

Only to a person, though. The shell integration runs auto on every cd and pipes it into eval; returning non-zero there would put a failing status into every prompt in every directory without a match, which is worse than the bug being fixed. The code is reported when stdout is a terminal and never to the hook, which is piped -- the same distinction nvx use already draws about whether to print its environment block.

A directory that declares no runtime, or already has the right one active, still exits 0. That is the ordinary case, not a failure.

Fixed

  • A DNS lookup that failed once was a way past the link-local guard. nvx refuses to reach 169.254.0.0/16 through a *name*, because that is where cloud metadata endpoints live and one unauthenticated GET there returns credentials. A name whose first lookup failed resolved to nothing, and the dial then fell back to handing the name to net.Dial — which resolved a second time with nothing judging the answer.

So a record that answers SERVFAIL to the first query and 169.254.169.254 to the second reached the endpoint the guard exists to protect. It needed an allowlisted host under attacker-controlled DNS, which is precisely the threat model the guard was written for.

The dial now resolves the name itself and applies the same check, so a name is never handed to net.Dial unjudged. A name that genuinely will not resolve still fails as a dial rather than as a containment decision, which was the reason the lookup error was swallowed in the first place.

Found by an independent audit, in code added the day before to close the first version of this same hole.

Fixed

  • nvx install tsc was refused as a typosquat of ms. TypeScript's compiler, at 780,294 weekly downloads, was reported as "suspiciously close to popular package ms (edit distance <= 2)" and the install aborted. In a non-interactive shell that is a hard stop: the only way past it was -y, which approves every prompt in the session, including a real typosquat.

Two things were wrong. tsc and ms share one letter, and at those lengths an edit distance of 2 is not a mistyping — nvx already refuses to suggest a command whose distance is not smaller than the word, and package names now get the same rule. And the authority test was a pure ratio, so ms having 700× more downloads outweighed tsc having 780,294 of its own; a package that is itself established by the same threshold the check uses to define "popular" is no longer treated as a squat.

Verified through the built binary, both directions: nvx npm install tsc installs, and expresss — 723 weekly downloads, one edit from express — is still refused.

  • Containment removed most of the environment without saying so. A tool that reads CI to suppress interactive prompts started prompting; a build reading NODE_ENV=production quietly emitted a development bundle. Neither failed, so there was nothing to search for, and nothing on screen connected the behaviour to nvx.

A contained run now says when it removes a variable that changes how tools behave, and names it. Ordinary runs stay quiet: the ~96 variables dropped on a typical Windows run are almost entirely operating-system furniture, and listing them every time would be noise. The complete list goes to the audit log on every contained run.

The reported set is curated, so it is incomplete by construction — a project's own variable is still dropped without a line on screen, and NVX_DEBUG=1 is where to look when something behaves differently inside the sandbox.

It has to stay short. NPM_CONFIG_* was on the list for a day: npm sets those for its own children, nvx shims npx, and the warning fired on 143 of 193 contained runs — a warning on essentially every start of an npx-based MCP server, which is noise rather than a warning. The same day's audit write was unconditional and put 600 entries and 849 KB into audit.log in a few hours; it is now recorded only when there is something to report.

  • nvx doctor said "nvx is intercepting commands correctly" on an install where version switching was entirely dead. Doctor checked one half of a working setup — is the shim directory on PATH, does npm resolve to it — and never looked at the other half, the shell integration. Without that line in the profile, nvx use 22 changes nothing and entering a project with a .nvmrc does not switch. Commands are still audited and contained, so the claim was true; it just was not the whole truth, and it was a green light on a half-working machine.

Doctor now names the profile it looked at and says whether it loads nvx, on both the healthy and unhealthy paths — a machine whose PATH is broken needs the integration too. nvx doctor --fix adds the line, creating the profile if it does not exist, in that shell's own syntax, and re-running it does not add a second copy.

Both installers already write this line, so anyone who ran install.ps1 or install.sh has it. Anyone who built from source, or copied a binary, does not — and nothing said so.

  • Every published overhead figure was measured from a command that failed, and has been withdrawn. scripts/bench.py timed the shim as nvx shim node --no-sandbox -e 0. nvx passes a wrapped command's own arguments through untouched on purpose, so --no-sandbox reached node, which answered bad option: --no-sandbox and exited 9. The wrapped half of the measurement was timing an argument-parsing failure against a real node run — on every platform, behind every figure this project ever published (~38 ms, then 9–57 ms, then 1–60 ms, then ~3 ms Linux / ~4 ms macOS). On Linux the failure is faster than starting node, so the corrected script reports a *negative* overhead for the old command.

The script now refuses to time an arm that does not exit 0 and print a marker from inside the runtime, so it can no longer publish a failure as a success. It also alternates the two arms and differences each pair instead of subtracting two independently drifting medians; the old design produced 140.0, 147.8, 92.9 and 42.5 ms on four consecutive runs of one idle laptop while the raw baseline alone swung 65→142 ms. When the spread is wider than the median it now says so instead of printing a figure.

Measured with the corrected script: about 75 ms on Windows (three runs on one machine, medians 73.8/74.2/77.1 ms, p10–p90 roughly 63–93; a fourth run on a busy machine was refused by the spread check). Linux in a container came out at 4–10 ms with the spread swamping it, and the script declined to give a figure. macOS has never been measured with a working script. README and PRODUCT.md now say exactly that.

  • Contained npx works without an elevated nvx setup, and no longer hangs when run outside a project. Two separate faults, both hit by an MCP client starting npx -y <server> under nvx.

npm's own realpath stats every directory above the cache npx uses; that cache sits in the sandbox's home under C:\Users, and an AppContainer with no drive-root grant gets EPERM on C:\Users and on the drive root. Measured 2026-09-03 with the grants removed: npm install in a project on C: works, npx -y cowsay hi from the same project fails with EPERM: operation not permitted, lstat 'C:\Users'. A preload in every contained node process now answers that stat, for the directories above the sandbox's own working directory and home only, with a directory's stats when the OS refuses the real ones. Those directories exist by construction and the sandbox may already pass through them; only their attributes were hidden. Measured afterwards, same machine, no grant on any drive root: npx -y cowsay hi works from a project on C:, from one on H:, and npx -y xtctx runs from its repo.

Separately, a command run from a directory with no package.json above it — %TEMP%, a home folder, the parent of all one's projects — got that directory as its writable root, and the ACL write for it propagated over the whole tree beneath: npx -y cowsay hi from %TEMP% (748,317 entries) and from H:\projects\private hung for over two minutes before the command started. One leftover permission from an older nvx on %TEMP% was rewritten the same way on every launch. Both writes are now bounded the way an ancestor grant is, and a directory that overran is remembered for a month. Because the sandbox cannot even start in a directory it holds no entry on, such a command starts in the sandbox home instead and says so; files it writes to its working directory land there and are removed with it. A project directory is never bounded: writing it is the point of an install. Measured afterwards: npx -y cowsay hi from %TEMP% in 7.8 s, from H:\projects\private in 6.2 s with the one-line note.

  • Every contained command on Windows paid about nine seconds of permission writes before anything ran. Measured 2026-09-02 with timestamps inside one contained npm install of a package that was already installed: 6.0 s writing read/execute over the node install, 3.0 s in two traverse grants timing out, 0.7 s for everything else nvx did, and 2.2 s for npm itself. Uncontained, the same command took 2.2 s.

Two things had gone wrong together. Since sandboxes became one AppContainer package per project, every project had been writing its own entry into nvx's *shared* directories — 388 identities on one node install, 39 on ~/.nvx/sandbox_home — and the check meant to make a second launch free asked for modify rights where the grant had written traverse, so it never matched and the same writes were repeated on every launch. The write on ~/.nvx never finished inside its timebox, so every run also printed a warning that the sandbox could not stat its own home and npx would fail there — while npx worked, because that entry was never needed.

nvx's own read-only trees — the runtime, the staged supervisor, the parent of the guest home — are now granted once to a single identity every sandbox carries, and the check asks for the right it wrote. What must stay per project, write access to the guest home and the project directory, still does. The first write a tree gets under the new identity also removes the per-package debris in the same propagation, at no extra cost. Measured afterwards on the same machine: contained 3.0–3.5 s against 2.4 s uncontained, no warning, and one entry on each tree where there had been hundreds.

  • nvx doctor now reports the permissions the sandbox actually has, not what a previous setup wrote down. It compared the identity recorded by the last *completed* nvx setup against the one nvx launches under, and called the machine broken whenever they differed. That record is only written when a setup run finishes, so a run interrupted part-way through a slow volume left it naming the old identity while the volumes it had already granted carried the new one.

Measured 2026-09-02: two cancelled runs, three volumes correctly granted, and doctor still reporting that an earlier setup "granted an identity nvx no longer uses" and that npx "fails there with EPERM" — neither true of that machine by then. It now names only the paths genuinely missing, says such a tool *may* fail there, and points out that an EPERM inside ~/.nvx is a different problem needing no elevation.

  • Contained npx no longer breaks itself for thirty days after one slow moment — and did not need an Administrator to fix. nvx grants the sandbox permission to walk the directories above its own home. Those grants are best-effort, and one that overruns is remembered and not retried for thirty days. That is the right call for the directories above your *project*, where it was measured: a contained command runs fine without them.

It is the wrong call for the directory above the sandbox's home, which npx genuinely needs. On the development machine one overrun on 2026-08-29 put ~/.nvx/sandbox_home on that list, and every nvx npx afterwards failed with a raw npm error — EPERM lstat ...\.nvx\sandbox_home — for eleven days. The only sign at the time was a line saying some permission checks had been skipped "to keep startup fast".

Worse, nvx pointed at the wrong fix. It reported that an earlier nvx setup no longer applied and told you to re-run it elevated, which would not have helped: the failing path is inside nvx's own directory and nvx setup does not grant it. Deleting one cache entry made the same command work, unelevated.

That chain is now never skipped, a failure there is reported instead of remembered, and the setup notice no longer claims to explain a failure it may have nothing to do with. It also stops listing volumes this run has no reason to touch, and stops printing the current one twice.

  • A command run without the sandbox no longer outlives nvx. When nvx stopped waiting on an uncontained command — because whatever started it went away, or because nvx was killed — the program nvx had launched kept running, with no parent and nothing left to stop it. Contained commands have been reaped since the orphan work; the uncontained path never was, so the leak had moved down one level rather than gone away.

Measured on the development machine: 92 stranded processes holding 78 consoles open and 1.6 GB between them. They came from nvx's own test for this problem, which checked that nvx exited and stopped there — so it left one behind every time it passed, and its comment claimed a cleanup that path never performed.

The trade: a process deliberately left running in the background by a command started through nvx now ends when nvx does. That was already true of anything sandboxed.

  • An allowlisted name that points somewhere internal is no longer followed there. The allowlist decided a hostname; the connection then went wherever that name resolved, and nothing looked at the answer. A name resolving to a link-local address — where every cloud keeps its credential endpoint, reachable by anything that can make one unauthenticated request — was reached. nvx now refuses that, while still allowing what it always has: an address you wrote in the policy yourself, and ordinary private-network services like a LAN database.
  • A misspelt policy setting is now reported instead of ignored. "blocked_packges" parses cleanly, exits 0, and blocks nothing — every protection here is switched on by a key name, so any of them can be switched off by one wrong letter that looks like it worked. nvx now names the unrecognised setting and suggests the one you probably meant. It warns rather than refuses: policy files legitimately carry keys a given version does not know, and refusing to run over a stray key would be worse than the problem.
  • Weakening a protection by number now asks, like weakening it by switch already did. A project policy could halve the typosquat sensitivity, or cut the release-age cooling-off window from a day to an hour, with no prompt — only on/off settings and list additions were treated as needing approval.
  • The typosquat check no longer quietly shrinks to a fraction of its dictionary. nvx compares the package you are installing against a list of around 2,000 popular names, refreshed weekly. Once that copy was a week old it was thrown away and the check ran against a built-in list of 33 names instead, while the refresh happened in the background for next time — and the output said "Verifying package" either way.

The old copy is now used while the new one downloads. The list it comes from is updated quarterly, so a week-old copy is almost always the same list; the built-in 33 are for having nothing at all, not for having something slightly out of date. On the machine this was found on, the check was a day away from dropping from 2,000 names to 33.

  • A vulnerability scan that could not finish no longer reports as clean. If the vulnerability database answered for fewer packages than were asked about, the unanswered ones were treated as having nothing against them and the run printed "Vulnerability scan clean. No active CVEs found." The same happened when the database had more advisories for a package than fit in one answer. Both now report that the check could not be completed, which asks you whether to continue — the choice nvx already offered when the database was unreachable.
  • A project policy can no longer be swapped between being read and being checked. When a project's .nvx-policy.json asks for something more permissive than the defaults, nvx checks it against the version you approved before honouring it. It read the file twice to do that — once to understand it, once to check it — and anything able to write the project folder in between could have the permissive version obeyed while the approved version was checked. Contained code can write that folder, which is the whole point of it. The file is now read once.
  • nvx setup --undo no longer says it removed things it could not remove. It warned about each failure and then printed success and exited 0 anyway. The one that matters most is the loopback exemption: while that is present, nvx's own documentation says the network allowlist can be worked around — so you could run the cleanup, see a tick, and still be exposed. It now names what it could not undo and fails.
  • nvx grants reset no longer quietly drops a permission that grew. If a folder's permission had been widened beyond what nvx originally gave it, nvx deliberately left it alone — correctly, since it is no longer nvx's to remove — but then deleted its own record of it and reported success. It now tells you what it left behind and how to remove it, and fails. This is the same defect as the renamed-folder one below; both were found by review rather than in use.
  • nvx doctor --fix no longer changes your permanent PATH without saying so first, and will never put a temporary folder there.

--fix edited the persistent user PATH whenever it could, while the offer to do it was only shown when the PATH was the thing that looked wrong. So a machine with a healthy PATH and some unrelated problem was never told, ran --fix for the other problem, and had its PATH changed and announced afterwards. It now only applies what it has already reported.

Separately, --fix would happily write whatever NVX_HOME pointed at into that permanent PATH — including a temporary folder, which is how machines end up with a dead ...\Temp\...\bin entry on their search path long after the folder is gone. That is refused now, with an explanation.

  • nvx grants reset no longer reports success when it could not take a permission back. If a directory nvx had granted access to was renamed, the permission moved with it — Windows attaches it to the directory, not the path — so there was nothing to remove at the recorded location. The reset warned about that, then printed a tick and exited 0 anyway, having deleted the only record of which permission it was and where it had been.

The reset still finishes, so running it again is clean and the command cannot get stuck. What changes is that this run now says what it could not account for, prints the identity and the old path, and exits non-zero so a script can tell.

  • On Linux, a stray space in network.mode turned the network containment off. A project policy asking for "offline " — with a trailing space — silently got the full host network, and the prompt that exists to catch a project loosening nvx's settings did not fire, because by its own measure the project had asked for something *stricter* than the default.

The value was checked with the space trimmed off and then stored with the space still on. After that the readers disagreed: the one that ranks how strict a policy is trimmed and saw "offline", while the two that actually build the Linux network sandbox did not, matched nothing, and quietly did nothing — no network namespace, and a syscall filter reported as installed that was never built. Windows and macOS were unaffected; neither uses this value to decide what to contain.

The value is now cleaned up once, when the policy is read, so every part of nvx sees the same thing. The two Linux readers also clean it themselves, because both of them fail *open* if they do not recognise what they are given, and one guard is not enough for that.

Changed

  • The terminal is quiet by default. A contained npm install printed ten lines of nvx before npm said anything — the package being verified, the scan starting, the scan being clean, a session id, a permissions count, two lines about an old nvx setup, the isolation being active — and a plain node x.js announced on every run that it was not sandboxed. Now a contained command prints one line, Running in native sandbox: npm install is-odd, and your own code prints nothing. Warnings and errors are unchanged. The rest is behind --verbose (or NVX_VERBOSE=1), and NVX_TRACE=1 still records every run.

The two-line warning about an earlier nvx setup having granted an identity nvx no longer uses fired on every package-manager run, by design, on the reasoning that the condition breaks npx. Measured twice, it does not: contained npx runs unelevated with those grants stranded. It is now shown once per identity and path like the other drive-root advisory, and repeated only after a package-manager command has actually failed. It had also been comparing the wrong right, so a completed setup still read as missing.

  • nvx no longer asks you to run an elevated nvx setup. A missing drive-root grant was two warning lines on every package-manager run and a red FAIL in nvx doctor, both saying npx may fail without it. Measured, it does not: installs and npx run contained with no drive-root grant at all. The grant serves a tool that resolves a path all the way to a drive root, and no such tool has been measured; asking for Administrator rights on a drive root is a lot to ask for that, and on one machine it cost a 22-minute ACL write over 5.6 million entries that nothing had needed.

Now the only time nvx names nvx setup is after a contained package-manager command has failed, as one thing the EPERM above it might be. Doctor lists missing roots as a note and the machine stays healthy; --verbose still shows the launch-time detail. The README entry that said npx needs setup is corrected, and the help text says the command is optional and slow.

Correction, one day later. The paragraph above was written on a machine whose drive roots were granted, and "npx does not need the grant" was not measured with the grant absent. Measured 2026-09-03 with it removed: npm install works, contained npx fails with EPERM lstat 'C:\Users' from npm's own realpath, which walks every directory above the npx cache in the sandbox home. So npx did need C:\Users readable, and nvx setup was the only way to get it. It is not any more: a preload in every contained node process now answers a stat for the directories above the sandbox's own working directory and home, which exist by construction and which the sandbox may already pass through. Contained npx runs on a machine that has never run nvx setup (measured: same project, no grant, npx -y cowsay hi works, and so does npx -y xtctx from its repo). What nvx setup still serves is a non-node tool that walks to a drive root.

  • Windows: a command run through nvx starts fewer processes. npm run dev, where dev runs node -e ..., is a tree of 5 processes instead of 7, counting the shell that typed it and the node that runs the script. Measured 2026-09-02 with Get-CimInstance Win32_Process, launched from cmd.exe with ~/.nvx/bin first on PATH:
  before                                     after
  cmd.exe /c "npm run dev"                   cmd.exe /c "npm run dev"
    nvx.exe shim npm run dev                   npm.exe run dev            (nvx)
      cmd.exe /c ...\npm.cmd run dev             node.exe npm-cli.js run dev
        node.exe npm-cli.js run dev                cmd.exe /d /s /c node -e ...
          cmd.exe /d /s /c node -e ...               node.exe -e ...
            nvx.exe shim node -e ...
              node.exe -e ...

Three things changed, all on the uncontained path only; a sandboxed run is launched exactly as before.

  • The shims in ~/.nvx/bin are now node.exe, npm.exe, npx.exe, yarn.exe, pnpm.exe, bun.exe and bunx.exe — each a hard link to the nvx.exe beside them (a copy where the filesystem cannot link). They replace the .cmd, .ps1 and extensionless files an older nvx wrote, which are removed when shims are regenerated. cmd.exe, PowerShell and Git Bash all resolve the .exe first, so there is no longer a shell process between your shell and nvx, and Git Bash no longer needs a script of its own. nvx recognises the name it was started under; npm --no-sandbox install still hands --no-sandbox to npm, as it did before. nvx init-shims, nvx env and nvx doctor --fix rewrite the links, and relink them when nvx.exe has been replaced by an upgrade — a link points at the old file otherwise. nvx doctor now reports a command whose .exe shim is missing.
  • npm and npx are started as node.exe npm-cli.js, the way the sandbox already did, instead of handing npm.cmd to cmd.exe. A self-updated npm in the version's npm_global prefix keeps running its own npm-cli.js. Exit codes are unchanged (checked: node -e "process.exit(N)" comes back as N from all three shells, and a missing npm script exits 1).
  • Inside an uncontained run, node is the real node. The child gets a PATH entry, ~/.nvx/direct/<runtime>/<version>, holding only that version's node.exe (or bun.exe), so a script's own node calls no longer come back through nvx. Only the runtime executable is there: a nested npm install in a script still resolves to the shim and is contained as before (measured: npm run inside a script shows npm.exe in the tree, and node inside it does not). nvx uninstall removes the entry with the version.

Project-bin shims (~/.nvx/project-bin/..., for node_modules/.bin tools) are still .cmd files and unchanged.

  • nvx setup no longer grants volumes nothing uses, and says what it is doing while it works. It granted the root of every fixed volume on the machine. The permission is narrow — read/execute on the root folder only, not inherited, measured not to reach any subdirectory — but the *cost* is proportional to the size of the volume, because Windows re-runs inheritance across everything beneath the directory it is writing.

Measured 2026-09-01 on a six-volume machine: a 932 GB drive with 1 GB free on a 5400 RPM disk had not finished after 36 minutes, and two more volumes were queued behind it — the last being the one holding the user's actual projects. A failure anywhere returned immediately, so the grant most likely to be lost was the one that mattered.

It now covers the volumes nvx, your profile and the current directory live on, names the ones it left alone, carries on past a failure instead of abandoning the rest, and skips volumes already granted — so a re-run resumes rather than paying again for what finished. Run it from the volume your projects are on, or pass --all-drives for the old behaviour.

Interrupting it loses that volume's progress, so it now reports every 30 seconds that it is still working, and says so. Measured 2026-09-02: a run stopped part-way through a 1118 GB volume left no entry on the root at all — the write does not commit until the propagation behind it completes. A timeout was tried and removed for that reason: it could not make the operation safe, only guarantee that a volume needing longer than the timeout was never granted.

  • Documented: a package.json above your projects puts them all in one sandbox scope. nvx picks a sandbox's project by walking up to the nearest package.json, so two projects that resolve to the same root share one identity and a contained install in either can reach the other. Each project normally has its own manifest, so they stay apart; a stray one in a parent — a home directory is the easy way to get one, from an npm install in the wrong folder — quietly merges everything beneath it.

Found because nvx's own containment probes reported a cross-project read after an npm install ran in a home directory. The behaviour is unchanged and now appears under Known limitations rather than being left for someone to discover; nvx doctor still does not check for it, which is stated there too.

  • Every prompt now defaults to "no", and answering one no longer grants anything for ever. Two changes to the same moment, both found by an independent review rather than by anyone being bitten.

Pressing Enter at a prompt used to mean yes. Every question nvx asks is about whether to permit something — trust a project policy that loosens settings, allow an outbound connection, grant a tool access, install despite known vulnerabilities — so a stray newline in the console was an approval. It now reads [y/N] and only an explicit y approves.

Approving an outbound connection also used to record that host permanently. The prompt said "allow outbound connection to X?", said nothing about persistence, and a reviewer approved a host once and then reached it in a later run with no prompt at all. An approval now lasts for the run in progress. To allow a host durably, put it in isolation.network.allow_hosts, where it is written down and can be read in a diff. Hosts persisted by an earlier version keep working, still show in nvx grants list, and are still removed by nvx grants reset.

  • nvx will not offer a local service through a prompt. Reaching localhost from a sandbox is supported and unchanged when the project policy asks for it — "allow_hosts": ["localhost:5432"] — and --connect still grants one port for one run.

What is gone is the path where the sandbox's own contents cause the question to be asked. The prompt is triggered by whatever is running inside, which is the untrusted code, and the services listening on localhost are the ones that take no credentials because they assume anything local is trusted: databases, dev servers, other agents' tooling. A package's install script must not be able to ask the developer for their database. Such a request is now refused outright, with a message naming the two deliberate ways to allow it.

docs/enforcement-matrix.md claimed a local service was reachable "only with a leftover exemption" and "only via --connect". That was true before the egress relay and has not been since — the proxy runs outside the containment and dials on the sandbox's behalf, so an allowlisted destination is reachable whether or not it is local. The table and SECURITY.md now say what the code does.

  • Why the first contained launch in some projects is slow, corrected. nvx gives the sandbox permission to walk through the folders above your project, and on some machines those writes take so long nvx gives up on them and carries on without. That much was already true and already handled.

What nvx said about the cause was wrong. It blamed OneDrive and antivirus, and on that basis expected the problem to clear up by itself one day. Measured: the cost is simply how much is inside the folder. Setting permissions on a folder makes Windows walk everything beneath it — about a second per five thousand items — and on this machine AppData\Local\Temp holds 748,317 items and AppData over two million. One of those writes, given no deadline, took three minutes and forty-five seconds and then succeeded.

So it is not a stall waiting on a driver, and it will not fix itself: profile folders only grow. Nothing about how nvx behaves changes here — it already gave up quickly and remembered not to retry — but the explanation a maintainer reads, and the reasoning behind how long it remembers, now match what was measured.

  • Windows permissions are set through the Win32 API instead of the icacls command. Every filesystem permission nvx grants, reads or withdraws now goes through GetNamedSecurityInfo/SetNamedSecurityInfo, which return a real error code for every operation and hand back structured entries with numeric access masks.

This removes the cause of a defect found in each of four independent acceptance passes, rather than the latest instance of it. icacls reports success it did not achieve, its output has to be parsed to learn anything, and its notation collides with the data being read — a directory named d(M)x was read as holding write access, and a path containing (I) as an inherited entry. Both of those shipped. Its output is also localized, so any parse of it is correct only in English.

Side effect: one fewer process spawn per permission check on the launch path. Measured interleaved over ten pairs of contained launches against a fresh nvx home: median 4596 ms before, 3989 ms after.

The one remaining icacls call sets the low integrity label on the guest home. That is a different mechanism and not part of this class.

Fixed (found by an independent acceptance pass before release)

  • A policy file with a UTF-8 byte-order mark now loads. Windows writes one by default — Notepad does, and so does PowerShell's Set-Content -Encoding utf8 — and Go's JSON parser does not skip it, so a policy written the ordinary Windows way failed with invalid character 'ï' looking for beginning of value. Because nvx refuses to run when it cannot read its own policy, the whole command was refused, with a message about the policy rather than about the encoding. The mark is now stripped before the file is parsed, and before the bytes that pin a trusted project policy are hashed, so adding or removing one is not a change the user has to re-approve.
  • nvx grants reset --all no longer reports a success it did not achieve. A grant record it cannot read is left in place, and so is every filesystem permission that record names — which is right, since deleting it would destroy the only trace those permissions exist. But it then printed Reset all project grants. and exited 0 anyway, two lines after warning it had skipped the record. A script that runs this to clear a machine's sandbox permissions read that as done. It now reports what was left behind and exits non-zero; the single-project form already did.
  • The Windows containment gate can run. scripts/sandbox-enforcement-windows.ps1 aborted before making a single assertion, on every invocation since it was written, and exited with a PowerShell error rather than one of its own FAIL messages. Cause: the script sets $ErrorActionPreference = 'Stop', and 2>&1 turns a native command's stderr into error records, so nvx's ordinary progress output terminated the script at the runtime install. Its careful exit-code check never got to run. Capturing output now goes through a helper that relaxes the preference for that call alone, which fixes the three other capture sites that had the same trap — including the probe that decides whether a host can create AppContainers at all. docs/enforcement-matrix.md cites this script as the source of the word "measured" in its Windows column. The BOM defect above was found the first time the repaired gate reached its assertions.
  • A --connect grant is now confined to the sandbox that asked for it. It was not. Windows permits loopback within an AppContainer package and every nvx sandbox shares one package identity, so the in-sandbox listener was reachable from every other nvx sandbox running at the same time: measured, a sandbox in an unrelated project with no grant of its own read the granted service. nvx now identifies the process behind each tunnel connection, refuses any that is not part of this run, and logs the refusal. Unverifiable peers are refused rather than admitted. This was a known hazard in the wrong place -- the egress relay has the same exposure and has defended itself with a per-session credential since an acceptance pass found the equivalent attack on 2026-08-19.
  • A directory granted by allow_read_exec no longer becomes permanently unwritable if it is later used as a working directory. The check for an existing grant matched on identity alone, never on which rights were held, so a read-only entry convinced the modify grant it had nothing to do. Every write in that directory then failed with EPERM, and nothing in the product could clear it -- repeat runs, grants reset --all, doctor --fix and deleting the policy entry all left it broken. Removing the entry by hand made it worse: the grant cache still reported success, so no grant was re-applied and contained commands could not even enter the directory. Rights are now part of both the check and the cache key.
  • An explicit --connect <host>:<inside> is no longer overridden by a policy entry for the same port. The policy won the de-duplication silently, handing back a different in-sandbox port, so a command line naming the port it asked for pointed at nothing.
  • A self-referential %VAR% in a policy path no longer hangs nvx. Expansion restarted from the beginning of the string after each substitution, so a variable containing its own name looped without bound and nothing launched -- no error, no output.
  • nvx no longer reports withdrawing a permission it did not withdraw. Success was taken from the exit code of icacls, which returns 0 whether it changed anything or not — on a path it cannot find it prints "Failed processing 1 files" and still succeeds. A permission is attached to a directory, so renaming one carried it to the new name while the record still named the old path; the withdrawal removed nothing, reported success, and the record was deleted. Every "the withdrawal failed, keep the record" branch added in earlier fixes was unreachable, because the condition they tested for could not occur. Grants and withdrawals are now confirmed by reading the permission back, which is also independent of the language Windows is running in.
  • A permission is never granted before it can be recorded. A grants file that could not be written produced a warning saying nvx would not be able to withdraw the grant later — and then granted it anyway, leaving a permission nothing on disk named. The record is written first now, and the run stops if it cannot be.
  • The read/execute answer is no longer cached. A permission removed behind nvx's back — with the very icacls command nvx's own messages suggest — left the cache reporting it as granted for seven days: the grant was skipped, the log said it had been made, and the sandbox got EPERM on a directory the policy still named.
  • A lost grant record no longer strands a permission for ever. Only what a run had just written was recorded, and an entry from an earlier run was indistinguishable from someone else's, so once a record was lost — a corrupt file, a deleted grants directory, one failed save — every later run re-confirmed the permission and declined to write it down again. nvx now recognises its own entry by its exact signature, so the record is re-created and the permission can still be withdrawn.
  • nvx grants reset no longer deletes a record it has just reported it cannot act on. An unreadable record was treated as one holding nothing, so it was removed along with the rest — destroying the only trace of permissions still on disk, and reporting success. It is kept and counted now. A second unreadable record also no longer overwrites the first.
  • Withdrawing a grant now clears the cache for the whole directory tree. The entries nvx writes are inheritable, so withdrawing one on a parent removes the access its children had through it; the cache still listed those children as granted, so their grant was skipped and the sandbox got EPERM on a directory the policy still named — for up to seven days, while the log said it had been granted.
  • Withdrawing a read/execute grant no longer removes a permission nvx did not grant. Withdrawing is not selective -- it removes an identity's whole entry on a directory, not one right from it. Two things made that destructive: a grant skipped because a broader entry already covered it was still recorded as though nvx had written it, and reclamation ran after the writable roots were established rather than before. Naming the project's own directory in allow_read_exec and then removing it therefore deleted the write access the project needed, and the next run died with "chdir: Access is denied". Only what nvx writes is recorded now, and reclamation runs first so anything still needed is re-established after it.
  • A permission check no longer reads the directory's own path as permissions. It matched on the whole line of icacls output, which begins with the path, so a directory whose name contains (M), (RX) or (R) was read as already holding those rights -- the grant was then skipped and the wrong answer cached, leaving the sandbox unable to reach a directory the policy named.
  • A grant record that cannot be read is no longer discarded. It was parsed leniently and then overwritten, which stranded every permission it listed: invisible to reclamation and to nvx grants reset, removable only by hand. It is now kept under a .unreadable name and reported. Records are also written atomically, so an interrupted write cannot produce that state in the first place.
  • TestReadExecRootsAreNeverWritable now tests what it claims. It asserted that an unrelated directory was absent from a set built from two other paths -- true regardless of what the code under test did, and it passed with the enforcement path deliberately given write permissions. It now checks the access mask the rule is built from. Its comment also claimed the Windows side was covered by an enforcement probe; no probe covers this feature, and the claim is gone rather than reworded.

v0.5.7

match a package-manager verb.** A project with a script called update, create, rebuild, dedupe, upgrade or add had npm run <that> silently contained — scrubbed environment, restricted egress, confined writes — around a command that is the developer's own code. Measured: npm run build ran directly, npm run update ran "in native sandbox".

  • cut, never published

Fixed (found by an independent acceptance pass before release)

  • npm run <script> is no longer sandboxed when the script's name happens to match a package-manager verb. A project with a script called update, create, rebuild, dedupe, upgrade or add had npm run <that> silently contained — scrubbed environment, restricted egress, confined writes — around a command that is the developer's own code. Measured: npm run build ran directly, npm run update ran "in native sandbox".

Widening the verb set in 0.5.6 turned a long-standing assumption into a live bug: both token scans read every non-flag argument, so a script's *name* was read as a subcommand. The scans now stop at run/run-script, after which everything belongs to the script — the same rule already applied to --.

The justification in the code was that mistaking a token for a verb "pushes a command toward MORE containment, never less — the safe direction". This project rejected exactly that reasoning for --strict one release earlier. More containment is not free when it lands on a command that was never untrusted, and on Windows a blocked write outside the project can report success while producing nothing.

  • nvx --help and README documented the pre-0.5.6 --strict rule, telling users it works "before the command or among its arguments". It has not since 0.5.6, so anyone following the help text believed their own code was contained when it was not. README also contradicted itself on the same page.
  • The comment in shim_options.go describing which smuggled flags are honoured has now been wrong in both directions at different times, and says so.
  • The hand-run Windows release gate could pass having asserted nothing: it exited 0 when Node was missing, and its runtime-install check read only the exit code of the *second* of two commands. Both are failures now — the same warn-instead-of-fail shape CI's Linux step was changed to reject.
  • Dead classification code for runtimes this build does not manage is gone. classifyInvocation still had branches for uv and deno, and uvx/pyx sat in the ad-hoc-tool list — left behind when the Deno, Go and Python providers were removed. None of those names is in any provider's shim list, so nvx never saw those commands and the code could not run. Unreachable code that reads as support for a runtime is worse than none; the real implementations are preserved on feature/polyglot-runtimes.
  • CI now prints the probe counts instead of the docs quoting them. docs/enforcement-matrix.md cited "442 pass and 35 skip" from a hosted Windows run someone had read by hand. It had already rotted once, and the correction could not be checked by a reviewer at all — a developer machine *runs* the probes a hosted runner skips, so the number was unreproducible by design. Every run now emits NVX_PROBE_COUNTS pass=… skip=… fail=… to its job summary and log, along with the distinct skip reasons, and the page says where to look rather than carrying a figure that goes quietly wrong.
  • nvx stopping a command 15–30 seconds after its launcher exits, with exit 129, is now documented in README rather than only in this file — including the case it can catch by surprise: a deliberately detached process that still has a pipe on its input.

Fixed

  • Sandboxed MCP servers no longer pile up after their client exits. Measured on the maintainer's machine: 18 nvx processes, 12 of them orphaned, 43 node processes holding 3.9 GB between them, the system freezing. Every orphan was nvx shim npx <an MCP server>.

nvx only left when two signals agreed: its input pipe had hung up *and* the process that started it had exited. On Windows a sibling that inherited the write end of that pipe keeps it open indefinitely, so the first signal never arrived. nvx had already recorded the reason itself, in its own hangup log: "the parent has exited, but something still holds the input pipe open".

The parent having exited is now enough on its own. That is safe because of when the watchdog arms at all: only when stdin is a pipe, meaning someone deliberately wired a channel to nvx. If the process that did that is gone, nothing is talking to it.

It does not reopen the regression the two-signal rule was added for. That was a finished shell pipeline, where the producer closes its end and the pipe reads as broken while the shell that built the pipeline is still waiting — the parent is alive there, so nothing fires. It was the pipe half that was the wrong signal. Both cases now have a test, and the orphan one was confirmed to fail against the old rule before the fix and pass after.

Deliberate detachment is unaffected: start /b leaves stdin a console, where the watchdog never arms.

v0.5.6

Aug 24, 2026

Commands that fetch and run untrusted package code were not being contained. They are now.

Security

  • Commands that fetch and run untrusted package code were not being contained. npx was; the identical operation spelled any other way was not:

These ran with no sandbox, no vulnerability scan and no typosquat check. npm exec cowsay fetched a package from the registry and executed it uncontained, while npx cowsay — the same thing — was contained. npm rebuild re-runs every dependency's install scripts. npm audit fix is the command you run *because of* a security advisory. npm create vite is how a project starts.

README claimed the opposite in four places and SECURITY.md in one, and no limitations section mentioned it. No test covered it in either direction, which is why it survived: the classification tests listed npx, bunx, uvx, pyx and stopped. Found by an independent acceptance review of the 0.5.5 build, which is why 0.5.5 was never published.

The reverse is now tested too — npm run build, npm test, a bare npm init and npm audit without fix still run uncontained, because a security tool that contains everything is one people switch off.

Fixed

  • --strict is no longer read from a command's own arguments. It must lead, like --no-sandbox and --standard.

It was honoured anywhere on the reasoning that it only ever *adds* containment, so smuggling it gained nothing. True of an attacker, wrong for everyone else: --strict is TypeScript's most-used flag and ESLint's. nvx tsc --strict meant "typecheck strictly" and nvx read it as "sandbox this", moving the command into a container where writes outside the project are redirected to a throwaway home — and on Windows such a write reports success, so a build could appear to work and produce nothing.

Same defect as 0.5.5's fix for nvx *removing* those flags, in the opposite direction: both came from treating a word that belongs to other tools as nvx's own. nvx still notices it and now says why it did nothing.

  • A skipped privileged containment test fails CI instead of warning. The step printed "it is verifying nothing" and let the job go green — the exact condition that let three Linux checks report success for months.
  • Documentation corrected where it was less careful than the code: SECURITY.md said "shimmed commands run inside an OS-native sandbox" without the your-own-code distinction README makes; the NVX_PROBE skip count in CONTRIBUTING.md counted top-level skips while go test -v prints one more for a subtest.

v0.5.5

Tagged and built, then blocked by an independent acceptance review that found the containment gap listed under 0.5.6 above. Nothing was released under this version; everything below ships in 0.5.6. Kept as its own section because the work is separable and the reason it did not ship is worth being able to find.

  • cut, never published

Fixed (found by an independent acceptance pass before release)

  • nvx no longer takes your program's arguments away from it. It read its own flags — --no-sandbox, --strict, --standard, --filesystem-provider — out of a wrapped command's arguments and *removed* them, anywhere in the line, past --, silently:
  nvx npx tsc --strict            → tsc ran WITHOUT --strict
  nvx npx electron --no-sandbox   → electron never saw it
  nvx node app.js -- --strict     → stripped past the end-of-options separator
  nvx node app.js --filesystem-provider notes.txt keep  → "notes.txt" eaten too

Those names are not nvx's to take: --strict belongs to TypeScript and ESLint, --no-sandbox to Chromium and everything embedding it. A non-strict typecheck was being reported as a strict one, with no error. It applied to uncontained runs too, where nvx has no security interest at all.

nvx now *notices* these flags without confiscating them, and stops reading at --. The anti-bypass rule is unchanged and still tested: a weakening flag smuggled through a package manager's arguments is still refused — it is just passed on to the program as well, and you are told it was ignored. --filesystem-provider now only reads the documented = spelling, because finding the value of the separated form meant consuming an argument that belonged to the program.

  • The loopback-exemption warning is now tested on a healthy machine. It is the only mitigation for a hole this project's own documentation calls serious, and the single test covering it skipped unless the machine already carried an exemption — so it skipped in CI and everywhere else, while the enforcement matrix claimed the check was "pinned by" it. The detection now has a seam, and four tests cover the exempt branch, the healthy branch, and the nvx doctor line that had no test at all.
  • The Windows containment gate can no longer pass by mistaking a regression for an environment limit. It skipped on *any* launch failure, so a change that broke every launch would have read as "this host cannot create AppContainer children". It now skips only on the two refusal shapes a hosted runner actually produces, and fails on anything else.
  • A release can no longer be built from a commit whose CI has not passed. The release workflow tested only on Ubuntu and did not wait for the cross-platform run — the v0.5.5 draft was complete while that commit's CI was still going. It now waits, using gh rather than a third-party action, because this is the job that publishes the binaries of a supply-chain security tool.

Added

  • --expose: a server running inside the Windows sandbox can now be reached from the host. A contained npx vite used to bind its port, print that it was listening, and serve nobody — Windows refuses connections into an AppContainer, and no setting changed that.
  nvx --expose 5173:8080 npx vite

Also settable per project as isolation.network.expose_ports: ["5173:8080"]. Omit the second number and nvx picks a free port and prints the URL.

The two numbers cannot be the same. An AppContainer shares the host's network stack rather than getting its own, so one port cannot hold both the contained server and the host listener; with both set to 51733 the contained server lost the race and died with EADDRINUSE. Give the port your server uses inside, then the port you want to visit.

Nothing is relaxed to make this work. The contained side dials *outward* over a UNIX socket and the parent splices inbound requests onto those tunnels, so no network capability is granted and egress stays exactly as restricted. The end-to-end test asserts both in the same run: the host reaches the contained server, and the contained process still cannot reach the internet. Adding a port to a project policy counts as loosening it, so it needs the same approval an allowlist entry does — publishing puts whatever the sandbox serves onto loopback, where a browser extends it the trust localhost carries.

Changed

  • Windows containment can now be re-checked by running one script, rather than resting on having been measured once. scripts/sandbox-enforcement-windows.ps1 joins the Linux and macOS probes and asserts the same five outcomes: writes and reads outside the project denied, both allowed inside, egress denied with an empty allowlist. Verified on Windows 11, including the control that matters — run with containment off, the same probe reports the opposite and the forbidden file appears on disk, so it distinguishes a working sandbox from a broken one.

Hosted Windows runners refuse to create AppContainer children, so this cannot be gated in CI the way the other two are. It is a documented pre-release step in CONTRIBUTING.md, together with the NVX_PROBE=1 suite — the twenty-odd end-to-end checks that skip on hosted CI and cover a sandbox reading another project, a deny ACE hiding a secret, and a session reading another's guest home. Last measured 2026-08-23: 319 pass, 0 fail, 3 expected skips, each named so a fourth is a signal.

The existing Windows smoke test had the flaw the Linux enforcement script was written to fix: it checked a host write by writing through the sandbox's redirected %USERPROFILE%, which is meant to succeed, so it would have passed against a sandbox restricting nothing. It had no read assertion at all.

  • Contained commands on Windows got faster after a project's first run. Measured on Windows 11, a warm nvx --strict shim node -e 0: ~650ms before, ~390ms after. Bare node -e 0 on the same machine measures ~210ms, so most of what remains is Node starting rather than nvx.

Nothing about the sandbox changed. nvx was re-reading every access-control entry on every launch: 17 icacls processes per command, each measured at ~20ms. Sandbox setup measured ~410ms in total, of which the permission phase alone measured ~250ms. The permission work itself is trivial — the cost was starting a process to ask. About ten of those paths give the same answer on every run for a given project and runtime, so nvx now remembers which grants it has verified and stops re-asking.

Only *positive* answers are remembered, which is what makes it safe: a stale "already granted" makes a launch fail, and can never make the sandbox more permissive. Entries expire after a week, and any failed launch clears them all, so a permission removed behind nvx's back is repaired on the next run rather than needing anyone to know a cache file exists.

  • macOS now proves three things it previously only described. An allowlisted host must be *reachable* through the proxy, not merely a blocked one refused — every earlier assertion ran with an empty allowlist, so all of them would have passed against a sandbox that had failed to start. UDP is checked separately from TCP, and turns out to be refused harder than expected: at bind rather than at send. And nvx refusing to run at all when sandbox-exec is missing is now a test rather than a reading of the code.

One macOS claim is still not made: the outbound connection the probe watches being refused could be failing at DNS or at connect, and nothing distinguishes them. On macOS that difference is real, so it stays open.

Fixed

  • A hung AppContainer launch no longer takes the whole Windows test suite with it. One probe's launch stopped returning on a hosted runner, so go test hit its package timeout and reported failure for everything — a runner's shape presented as a product defect. It is now bounded, and reports "hung" distinctly from "refused" so a real regression cannot hide behind an environment excuse.
  • Two CI checks reported the wrong reason for skipping. The Windows egress smoke stopped on the runner's Node version before reaching anything about nvx; CI now installs a version that has the flag it needs, so it skips on the real blocker instead. Nothing about the product changed — only whether the log tells you the truth about what was and was not checked.

v0.5.4

Aug 23, 2026

The Linux sandbox could not run anything. Fixed.

Fixed

  • The Linux sandbox could not run anything. Every contained launch died with Sandbox execution failed: fork/exec <runtime>/bin/node: no such file or directory, naming a file that was present, executable, and inside the rules the sandbox had just granted.

It reported a missing file rather than a refusal because the supervisor runs in its own PID namespace with the host's /proc still mounted: the child's process id names nothing there, so the path fails to open before permissions are considered. The same launch outside that namespace says "permission denied".

The nested namespace is gone. The target keeps its own mount namespace, and takes the user namespace from the supervisor, which is where it belongs -- membership in that one is what allowed the mount namespace unprivileged in the first place. Nothing is less contained; a second namespace only gave the target a fresh one to be root in.

  • Three Linux checks in CI reported success without testing anything, which is why the above survived. Each gated itself on unshare -n, which an ordinary user is refused — nvx asks for a network namespace and a user namespace together, which is exactly what makes it available unprivileged. So all three skipped on every unprivileged machine, including the runner they were written for.

The containment probe additionally explained its own silence: finding no report from the contained process, it blamed the distribution for restricting user namespaces and exited zero, without checking whether they were restricted. They were not. It now tests that before deciding, and fails if the sandbox had every facility it needed and still produced nothing.

With them running, both smoke tests turned out to be launching their probe uncontained, so the one that checks a sandboxed process cannot write outside its project could never have passed and the other was measuring the host's internet connection. Both now run strictly contained.

Changed

  • The published guarantees now match the evidence, in both directions. README, SECURITY.md, PRODUCT.md and docs/enforcement-matrix.md said macOS was unverified at runtime and that Linux rested on privileged CI. Neither is true now: each runs an enforcement probe on a hosted runner of its own OS, asserting what must be denied *and* what must still be allowed, so a sandbox that refuses everything fails rather than passes.

Four macOS cells stay unclaimed rather than rounded up — that an allowlisted host completes through the proxy, that UDP in particular is refused, that nvx fails closed without sandbox-exec, and which layer refuses the outbound connection the probe does observe being refused.

macOS still does not contain reads. That is now asserted rather than merely admitted: the probe requires the read to succeed, so tightening the profile fails CI and forces all four documents to move in the same change.

v0.5.3

Aug 23, 2026

nvx audit: a local record of what nvx did, so questions that only show up across many runs have evidence behind them.

Added

  • nvx audit — a local record of what nvx did, for reviewing later rather than in the moment. ~/.nvx/audit.log already held security decisions (egress allow/deny, grants, policy pins) but nothing recorded that a command ran at all, so questions that only show up across many runs had no evidence behind them: how often something falls out of the sandbox and why, which warnings fire repeatedly and get scrolled past, what is slow.

With it on, each top-level invocation appends one record: command, subcommand, whether it was contained, why not when it was not, exit code, duration, and the warnings it printed. Nested invocations are not recorded — one typed npm command can spawn a tree of lifecycle scripts, and counting each would make every total wrong.

nvx audit prints them interleaved with the security decisions they caused; --summary gives counts, --failures narrows to non-zero exits.

Nothing is sent anywhere. The file is on local disk and there is no uploader.

Arguments are not recorded. A subcommand is, but only when the word is one nvx recognises — install, run, publish — and only when it can be reached without stepping over a flag that might take a value. Everything else is dropped rather than guessed at, because argv is where the private things live: npm config set //registry/:_authToken=…, node -e '<script>', node acme-client-secret.js, and yarn deploy-acme-prod, where yarn's bare positional is your own script name. This is the file a user would paste into a bug report. Warnings are recorded as their message template, never as the rendered text, so a warning that quotes a package URL stores …checks for %s. and not the credentials in it.

The live log is capped at 4 MB and one rotated generation is kept, so expect up to about 8 MB on disk. It grew without limit before, which was tolerable when only security events went in it.

  • A remembered permission failure no longer costs a slow command every week. nvx skips ancestor-directory grants that have failed before, because retrying them costs three seconds and buys nothing. Those records expired after seven days and all expired at once, so the first contained command after the deadline paid the entire three-second retry budget — against roughly 0.6s for a normal contained run.

Records now last a month, and at most one is re-tested per run. An environment that starts working is still noticed within a few commands; the cost of checking is about a second a month instead of three seconds a week.

  • A contained command can stream its child's output. spawn(cmd, {stdio: 'pipe'}) inside the sandbox used to block forever before the child existed — Windows builds piped stdio out of named pipes and a contained process cannot create one. Every contained npx vitest or npx playwright run left a process wedged until someone killed it; 17 were found on one machine, some blocked for 13 hours.

nvx now creates the pipes outside the container and the preload only opens them, which Windows permits when the pipe names both the user and that container's identity. Output streams as it is produced, stdout and stderr stay separate, exit codes propagate, and 20,000 lines arrive complete and in order.

One gap: writing to a contained child's stdin is not supported — child.stdin is null rather than a stream that silently discards.

Beyond 8 concurrent piped children in one process, output is collected and delivered when the stream ends rather than as it is produced. No bytes are dropped, but they arrive on close, not before exit — so a caller that reads its accumulated buffer in an exit handler sees it full for the first 8 children and empty for the rest. nvx warns once when a process crosses that line. Windows only.

  • Abandoned sandbox profiles are reclaimed automatically. They used to wait for someone to run nvx cleanup, and nobody did — 91 had accumulated on the development machine. Each run now reclaims a few after the command finishes, skipping any whose owning process is still alive, so a concurrent install cannot lose its home. Bounded per run, so one command never pays for a whole backlog.

A process killed outright cannot clean up after itself, so leftovers are unavoidable; needing a command to deal with them was not. nvx cleanup still reclaims everything at once, and still prunes staged supervisors from other builds — that part stays manual, because a supervisor another nvx has staged but not yet run cannot be told apart from an unused one.

Fixed

  • nvx processes piled up forever once the program that started them exited. Measured on a development machine: 48 live nvx processes, 38 of them orphaned, each still holding a sandbox supervisor, accumulating at about one per 60–80 seconds until Windows ran out of commit charge and builds started failing with "the paging file is too small". Nearly all were MCP servers started through nvx shim npx ….

nvx waits for the command it launched. An MCP server does not stop when its stdin reaches end-of-file — many do not — so when the client went away, the server kept running, nvx kept waiting, and nothing ever ended either. The process-tree cleanup that already existed was never the problem: it fires when nvx exits, and nvx never exited.

nvx now stops when two things are true together: the pipe it was given for input has lost its writer, and the program that started it has exited. Stopping triggers the existing cleanup and takes the sandbox with it.

Both conditions are required because either alone is wrong. A producer closing its end is how a pipeline is meant to finish — echo hi | nvx node … must not be killed — and a parent exiting is normal for deliberately detached commands. Only together do they mean nobody is left to talk to. If the parent cannot be identified, nvx leaves the command alone.

Windows only; on Linux and macOS the ordinary signal path already ends an abandoned process.

  • The README's command list was missing five commands, some for several releases: doctor, grants (both list and reset), import, setup and shim. A reader checking whether nvx could inspect its grants would have concluded it could not. nvx help had its own gap in the other direction — it never listed version.

Both lists are now complete, and a test compares them so the next omission fails instead of shipping. Nothing breaks when documentation is wrong, nobody re-reads a list they wrote, and the person who notices is the one who already gave up on the feature.

The README's flag section was also misleading: it listed --no-sandbox under "shim flags", which reads as npm --no-sandbox install. In that position the flag is stripped and ignored — deliberately, so nothing escapes the sandbox by appending a flag to npm. It only works as nvx --no-sandbox npm ..., and the README now says so. --strict and --standard were not documented there at all.

v0.5.2

Aug 20, 2026

The async-pipe limitation is documented for tool runners, not only for installs.

Security

  • "Builds coexist" was not true, and the prune that made it untrue could race a launch. Staged supervisor copies were pruned on every launch, keeping only the copy the running process wanted -- so alternating a release and a dev build re-copied ten megabytes each time, and a second nvx could delete the first's copy in the window between staging it and executing it. That is a narrower version of the race per-build naming exists to remove.
  • The async-pipe limitation is documented for tool runners, not only installs. npx/bunx tools that stream a child's output hang exactly as an install does, which README and SECURITY.md now say. The two-minute hint still covers installs only, deliberately: an install running that long is anomalous, an npx-launched dev server running for hours is working, and a timer cannot tell them apart. A hint that fired on the second would be noise, and a hint people learn to ignore is worse than none.
  • A typo in isolation.network.mode silently gave you more network than you asked for. An unrecognised value fell through to proxy in every reader, so a policy saying "offlin" got a live egress proxy while its author believed they had asked for no network at all. Nothing warned. The neighbouring isolation.level already reported an unrecognised value, and this is the field where being wrong grants more access rather than less.

Unrecognised modes now warn once, name the valid values, and are rewritten to proxy so no downstream reader falls into its own default arm -- which is also where the platforms diverged: the same typo produced proxy on Windows and Linux and no network rule at all on macOS. Warned rather than refused, matching isolation.level, and because proxy is the restrictive default: you asked for stricter than the default and get the default, loudly.

  • A corrupted staged supervisor bricked every contained launch, permanently. The staged copy's name encodes the source binary's size and timestamp and the reuse check compares size, so a corruption preserving size -- an antivirus quarantine stub, a cloud-sync placeholder, a bad sector -- was invisible to it. Every later launch failed identically, and neither cleanup nor doctor could clear it. Found by an acceptance pass zeroing 512 bytes in place; it is the failure the previous commit set out to eliminate, reached by another route.

An image error from CreateProcess now discards the staged copy and retries once. The trigger is narrow -- five image-specific Windows codes, matched by code rather than message text so it works on a localised Windows -- because a launch refused for permissions must not spin. The launch error is wrapped with %w for the same reason; it was %v, which stringified the code away.

  • A project whose path contained "(I)" hid its own pre-0.5.0 grant. icacls prints a directory's path on the same line as its first entry, and the scan skipped any line containing "(I)" in order to skip inherited entries. For such a path the skip swallowed that first entry instead, so a dangerous (OI)(CI)(M) grant was invisible to both doctor and the launch-path cleanup: the project stayed writable by every sandbox on the machine while doctor called the install healthy and --fix did nothing.

Inheritance is now read from the rights the SID carries rather than from the line, so the path cannot influence it. Same class of mistake as the one this function was corrected for one commit earlier -- matching on the shape of text instead of on its meaning. Pinned by a test using directories named proj(I)x and (I), confirmed to fail against the previous filter, with a companion test that inherited entries are still skipped.

  • README claimed contained dev servers work; on Windows they do not. The FAQ said loopback bind/connect works for dev servers, with no platform qualifier. A server started inside the sandbox binds and reports itself listening, but Windows refuses connections into an AppContainer from outside it -- the same restriction the egress relay exists to work around, and unaffected by the loopback exemption. nvx npx vite, npx serve and anything else serving a port appear to start and then serve nobody. Corrected in the FAQ and added to Known limitations, with the workaround: npm run dev is uncontained at the default level anyway, and nvx --no-sandbox npx <tool> covers the tool-runner case.
  • The stale-grant check reported live grants as leftovers, and --fix deleted them. The scan matched any AppContainer package SID on a directory, ignoring what the entry actually granted. But the current design writes (X,RA) -- traverse and read-attributes, non-inheritable -- on the directories above a sandbox so it can walk through them without listing them. Run nvx from a subdirectory and the project root carries one, so on a healthy machine doctor announced it as a pre-0.5.0 leftover letting "any nvx sandbox read and write this project", exited non-zero, and offered to remove it. False in every clause for a traverse-only entry, and the removal took out a grant nvx had just written. The regex also matched entries belonging to unrelated AppContainer applications.

The scan now matches on what an entry grants, not on the SID being present. Anything beyond the traverse pair is stale, a strict subset of it is not, and unreadable rights stay quiet -- this drives both a security claim shown to the user and a removal, so asserting either from an entry that could not be parsed is what caused the false positive. Legacy (OI)(CI)(M) grants still match. Introduced in the previous commit and caught by the next acceptance pass.

  • nvx doctor now finds the pre-0.5.0 grants that leave a project writable by every sandbox on the machine. Up to 0.5.0 every sandbox ran as one shared package identity and the grants it wrote were never revoked, so a contained install in one project can read and write another. The cleanup only ever ran on the working directory of the session currently running, so a project you do not revisit stays exposed indefinitely.

README has disclosed this since 0.5.0, and the containment behaviour is unchanged -- what was missing was any way to observe it. The comparable leftover, the loopback exemption, warns on every contained launch and fails doctor; this one was silent. An acceptance pass found 19 such grants live on the nvx repository itself while doctor reported a healthy install and exited 0, and wrote into that repository from a sandbox scoped to a different project.

doctor now reports leftover grants on the project it runs in, counts them against health, and removes them under --fix. nvx keeps no record of where it has run, so it cannot sweep the machine; the check answers for the directory you are standing in. It is not a launch-path warning because the launch path already removes them from the working directory before running anything.

docs/enforcement-matrix.md said an unqualified "Yes" for Windows write containment, contradicting README's own Known limitations. Corrected.

  • On a platform with no sandbox, nvx ran the command unprotected and said it had contained it. sandbox_native_other.go -- the path for any Unix that is not Linux or macOS -- set a process group, logged "using environment isolation only" at info level, and then executed the command. nvx printed "Running in native sandbox" around it. A contained install on FreeBSD therefore had full access to the user's home, their SSH keys and the network.

This is exactly what SECURITY.md's design stance rules out: if a containment primitive is unavailable, refuse to run rather than run unprotected. Every other platform honoured it. It now refuses, naming --no-sandbox as the deliberate opt-out. A scrubbed environment and a redirected HOME are worth having but are conventions the child can ignore, so they do not amount to a sandbox and are no longer presented as one.

No release binaries are published for these platforms, so this was reachable only by building from source -- which is exactly the person who would trust the word "sandbox" without checking. Closes F28, and with it F33, the last open contradiction of the fail-closed claim. Pinned by TestUnsupportedPlatformRefusesInsteadOfRunningUnprotected, which asserts the command left nothing behind rather than trusting its exit code.

  • On macOS, a contained process could reach every service on your loopback address. Every restricted mode emitted (allow network-outbound (remote tcp "localhost:*")), so an install could reach a local database, a daemon's TCP port or another project's dev server with no allow_hosts entry. Worse than it first sounds: any reachable service that forwards traffic -- a debugging proxy, ssh -D, a dev server's proxy route -- turns that into unrestricted egress, so the allowlist stopped meaning anything. network.mode: offline was covered by the same rule, so offline was not offline. Present since the sandbox was first implemented.

Loopback is now granted per mode. proxy reaches the proxy's own ports and nothing else; offline emits no network rule at all; loopback keeps the wildcard, that being the entire meaning of the mode. A proxy launch with no known proxy port now grants nothing instead of falling back to the wildcard. The per-port rules that already existed were dead code -- the wildcard above them had subsumed them since the beginning.

Pinned by TestSeatbeltGrantsLoopbackOnlyWhereTheModeMeansIt, confirmed to fail against the previous behaviour. This fixes the generated Seatbelt profile; per the enforcement matrix, no macOS hardware has yet confirmed the kernel enforces any part of that profile.

Fixed

  • Shims pointed at whichever binary generated them, so a source build broke them. generateShims embedded os.Executable(). Run init-shims from a build tree -- which the smoke scripts do -- and every shim depended on a file that gets rebuilt, moved or deleted, after which npm failed with a missing-file error naming a path in someone's source directory. It happened three times in one session on the machine this was found on, and left that machine with no working nvx on PATH at all, which is why the -g refusal's advice could not be followed. Shims now point at <nvxHome>/bin/nvx, where the installer puts nvx, and a copy is installed there if missing. Verified by running the smoke script and deleting the repo build: the shims kept working.
  • yarn global add was not recognised as a global install. Only -g and --global were matched, and yarn spells it as a subcommand -- so it fell through to the sandbox and failed partway with the confusing permission error that check exists to replace. yarn global add/remove/upgrade are now caught, by position rather than by containment, so yarn add global still installs a package called "global".
  • A failed contained install pointed at a debug log that had already been deleted. Reported from real use. npm writes its log into the cache, which nvx redirects into the guest home, and the guest home is removed when the run ends -- so the path npm printed was dead before the user finished reading it, on exactly the occasion the log is wanted. The logs are now copied to ~/.nvx/logs/<session> first, and only when the command failed; a successful run leaves nothing behind, not even an empty directory. The guest home stays ephemeral.
  • The loopback-exemption warning was four lines on every contained command. Every clause was true and worth saying once, but in a real transcript it was most of the output of an ordinary npm invocation, and a warning that dominates every command is one people stop reading. It is now a single line pointing at nvx doctor, which still reports the full explanation and the exact removal command and still exits non-zero. Still shown on every launch rather than once a day: it is a live weakening of the containment being asked for.
  • @latest silently skipped two security checks, and scanned the wrong thing. Reported from real use: npm install -g npm@latest produced a vulnerability alert listing seven advisories with no descriptions. The noisy output was the symptom. The cause was that version resolution replaced the query only when it was *empty*, so the literal string "latest" was carried forward -- and every lookup keyed on it missed:
  • meta.Versions["latest"] misses, so the install-script prompt never appeared for any @latest install;
  • meta.Time["latest"] misses, so the release-age check never fired;
  • OSV was queried for version "latest", so the scan was not about the version being installed.

Every dist-tag now resolves -- latest, next, beta, whatever a publisher defines -- and an exact version wins over a same-named tag. Verified against the live registry: npm@latest now scans clean, and esbuild@latest correctly warns about install scripts naming the resolved esbuild@0.28.2, which it previously did not warn about at all.

Behaviour change worth knowing: a semver range (lodash@^4.17.0) is now an explicit "could not verify registry metadata ... proceed?" rather than a silent pass. nvx cannot check a version it cannot name, and quietly running no checks is what this replaces. Resolving ranges properly would remove the prompt and is not done here.

  • Advisories printed as bare identifiers with no description. OSV's querybatch returns ids and modification times only, so every finding rendered as GHSA-xxxx-xxxx-xxxx: with nothing after the colon -- unactionable, and it reads like the tool is broken. Summaries are now fetched per advisory, best-effort and bounded: a failed lookup leaves the line exactly as it was before, so this can only improve the message and never blocks an install on a second network call.
  • A refused global install still ran a vulnerability scan and asked you to approve it first. Reported from real use. npm install -g npm@latest printed a scan, listed advisories, asked "Proceed with installation despite active vulnerabilities?", took the yes -- and then refused, because -g cannot run contained. The refusal depends only on the flags, so it was knowable before any of it. The delay is the smaller half: approving a security prompt for a command that could never run trains people to click through the prompt that matters. The check now runs before verification.
  • The refusal told you to run a command your shell could not find. It suggests nvx --no-sandbox ..., which needs nvx on PATH. The installer puts it in ~/.nvx/bin beside the shims, but a source build that runs init-shims leaves shims pointing into the build tree with no nvx installed -- and then the advice produces "The term 'nvx' is not recognized", which reads as the user's mistake. The hint now falls back to the running binary's absolute path when nvx does not resolve.

Two related hazards were found and are recorded, not fixed: shims embed the absolute path of whichever binary generated them, so running init-shims from a build tree makes every shim depend on a file that may be rebuilt, moved or deleted; and yarn global add is not recognised as a global install at all (globalInstallFlags is -g/--global), so it is contained and fails with the confusing permission error this check exists to prevent. Pinned by TestYarnGlobalSubcommandIsNotYetRecognised so it stays visible.

  • A hung contained process could block every later contained launch. The sandbox supervisor was staged under one fixed name, and Windows refuses to replace a running executable -- so a supervisor still alive from an earlier build held that file and the next launch died at staging with a bare "Access is denied", naming a path inside ~/.nvx that nobody would connect to their stuck process. The only cure was finding and killing it by hand. Asynchronous piped stdio still hangs, so leaving a supervisor alive is not a rare accident.

Staged copies are now named per build, so nothing is ever replaced: builds coexist and a leftover copy is inert rather than blocking. Copies from other builds are pruned when they are not in use, failures ignored, because a copy that will not delete is one another sandbox is executing. The legacy fixed-name copy is cleared on the next launch.

The name is derived from the binary's size and timestamp rather than a content hash: this is a launch path measured in milliseconds and hashing ten megabytes to learn what a stat already tells us would be a poor trade.

  • The macOS network mode was the only reader of that field not trimming whitespace. A policy carrying "mode": "proxy " was proxy on Windows and Linux and matched no case in the Seatbelt switch, so macOS emitted no network rule at all. It failed closed, but it was a silent, platform-divergent behaviour change from one trailing space in a config file.

Changed

  • The docs stop claiming macOS enforcement nobody has tested. Three tables printed the same "Yes" for Windows, Linux and macOS on guarantees backed by very different evidence -- measured, CI-tested, and never checked respectively. macOS cells now read "profile only" and say what that means. The one macOS check in CI asserts that a sandboxed process can write its own working directory and nothing about what is blocked, so it would pass against a build whose sandbox blocked nothing.
  • Two documents contradicted each other on a security question. SECURITY.md said macOS egress control was cooperative and a raw socket could bypass the allowlist; README said macOS blocks raw TCP/UDP at the OS. README was right -- the profile is (deny default) -- so SECURITY.md understated the design while the matrix overstated the evidence for it. Both corrected.