Known limitations
These are the places where nvx does not protect you or does not work. The threat model is in SECURITY.md, and the evidence and measurements for each platform are in the enforcement matrix.
Every platform
Section titled “Every platform”- Your own code is not contained by default.
npm run build,npm testandnoderun uncontained at thestandardlevel, and so does a compromised dependency they import. A contained install can write the project files those commands run, such aspackage.jsonscripts,node_modules, lockfiles, build config and hook folders like.husky.isolation.level: strictcontains them, at the cost of breaking anything that needs unrestricted filesystem or network access. - A
.envinside the project is readable by a contained install. The project directory has to be readable for the install to work, and.envlives in it. Scrubbing covers environment variables only. - Only an
http://upstream proxy is used. Anhttps://orsocks5://value inHTTPS_PROXYis ignored with a warning, and contained connections are then made directly. Behind a proxy, a host nvx’s own resolver cannot look up is still reachable when the allowlist names it, and cannot be approved at the prompt. - The Docker provider cannot do
proxymode. A policy that selectsisolation.filesystem.provider: dockerwith the defaultnetwork.mode: proxyis refused. Docker runsofflineandloopbackwith no network at all, andopenunfiltered. Use the native provider for an egress allowlist.
Windows
Section titled “Windows”- Your home directory is listable. Contents stay unreadable, so
~/.ssh,~/.awsand~/.npmrccannot be read, but their presence is visible. That is an access rule Windows ships on your profile, and nvx cannot revoke it. - A loopback exemption left by an older
nvx setupopens every service on 127.0.0.1 to contained code, whatever the allowlist says. Current versions never add one. nvx warns on every affected launch, andnvx doctorreports it. Treat the allowlist as unenforced until you runnvx setupfrom an Administrator terminal, which removes it. bun installworks contained only in projects on the drive Windows is installed on. On any other drive it fails withEBADF, and nvx names the cause. Windows refuses bun’s request to turn a file handle back into a path inside an AppContainer, and oven-sh/bun#38365 would fix it in bun. Usenvx --no-sandbox bun install, which runs it uncontained, or use npm, yarn or pnpm.yarnclassic fails in a project under your user profile if you have a~/.yarnrc. yarn reads every.yarnrcfrom the project up to the drive root, and treats the sandbox’s refusal of the one in your real home as fatal. Projects outside the profile are fine. Measured with yarn 1.22.19.- A contained process cannot create a pipe. nvx brokers synchronous and
streaming capture.
child_process.forkis refused outright, and the error names--no-sandbox. - A background process your own code started ends with nvx if nvx is stopped before the command finishes. That happens, for example, when the program that started nvx exits. A command that finishes on its own leaves it running.
- Reads outside your credential stores are not contained. The Seatbelt
profile has to allow filesystem reads, because the dynamic linker loads system
libraries whose locations move between macOS versions. It denies
~/.ssh,~/.aws,~/.npmrc, the other registry and cloud credential files, and your keychains by path. Other files can be read, including other projects and any credential kept somewhere the list does not name. - DNS lookups are not blocked. A contained process can still query the system resolver directly. Connections themselves go through the allowlist.
- A UNIX socket inside the project can be reached. A contained process sees
only the directories it is granted, so host sockets such as Docker’s are
absent. A socket placed in the project directory, or in a directory added with
allow_read_exec, can still be connected to. - On Ubuntu 23.10 and later, the sandbox may refuse to start. Ubuntu
restricts the user namespaces it is built on, through
kernel.apparmor_restrict_unprivileged_userns. Contained commands then fail with “Operation not permitted”, and nvx does not run them uncontained instead.nvx doctornames this setting when it is the cause, and says whetheropenstarts.sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0turns the restriction off for every program on the machine. Or setisolation.network.modetoopen, which gives up the network namespace, so contained code shares your network and the egress allowlist is not enforced.
Checks and registries
Section titled “Checks and registries”- Detection is best-effort. Typosquat and vulnerability checks reduce risk without certifying a package. Containment is the backstop.
- Dependencies are checked for npm installs, and not for everything.
npm install,npm updateandnpm dedupecheck every package npm will install, andnpm cichecks every entry ofpackage-lock.jsonfor this platform.npx,npm exec,npm create,npm init, every pnpm, yarn and bun command, and npm projects that use workspaces or depend on a local folder are checked on the packages they name, the entries ofpackage-lock.json, or the versionspackage.jsondeclares. The dependencies those bring in are not checked, and pnpm, yarn and bun lockfiles are not read. - Packages from git, a URL or a local path get only the blocklist. They are
checked against
blocked_packagesby the name they install under. The typosquat, advisory and release-age checks look a package up in the registry, and these are not in it. - Packages from a registry other than the public one get no typosquat or advisory check. Both ask a public service about a package by name, so nvx does not send them a private name. A registry that proxies the public one, such as an Artifactory or Nexus virtual repository, counts as another registry. The blocklist, release-age, install-script and lockfile checks still run against that registry’s metadata.
- A contained npm reads only the project’s
.npmrc. It gets a fresh home and none of yournpm_config_*variables, so a registry or scope set in~/.npmrcdoes not apply inside the sandbox. Your_authTokennever reaches the sandbox either, so a registry that needs one for downloads cannot serve a contained install. Put the registry in the project’s.npmrcand its host inisolation.network.allow_hosts. - yarn’s
.yarnrc.ymland bun’sbunfig.tomldo not change where the checks look. nvx reads registries from.npmrconly.