The Permission Model

Source: Node.js API: Permissions and Node.js API: Command-line options

Normally a Node.js process can do anything its operating-system user can do: read any file, open any socket, spawn any program. The permission model flips that default for the Node.js APIs: once --permission is on, each class of operation is refused with an ERR_ACCESS_DENIED error unless a matching --allow-* flag was given at start-up. The point is to stop trusted code (yours, your dependencies on a good day) from accidentally touching things it was never meant to touch: a build script that writes outside its output folder, a report generator that opens a network socket, a dependency that starts a shell. That is the "seat belt" the official documentation talks about.

It is not a sandbox. The documentation is explicit that the feature does not protect against malicious code, because Node.js trusts any code it is asked to run, and that malicious code can bypass the model and execute arbitrary code outside its restrictions. Treat it as one layer of defence in depth next to operating-system isolation (separate users, containers, seccomp or AppArmor profiles) and supply-chain hygiene, not as a replacement for them. The limits are listed with working demonstrations in Where the seat belt ends.

Source: Node.js API: Permissions

node --permission app.js is all it takes. Every restricted capability is off until granted. The first example probes four things (read a file, write a file, spawn a child process, start a worker thread) with and without grants. It assumes a folder app/ that contains probe.mjs, a data/books.json file and an empty out/ folder.

Source: Node.js API: Permissions, Permission Model

Source: Node.js API: --permission

The output below is identical on Node.js 26.10.0, 24.21.0 and 22.23.3 (observed). The entry point itself is always readable, which is why the script can start without any --allow-fs-read; that implicit read of the entry point, and of --require modules, is documented from v24.2.0 and v22.17.0.

The error carries two useful properties: code (always ERR_ACCESS_DENIED) and permission, which names the denied class (FileSystemRead, FileSystemWrite, ChildProcess, WorkerThreads, Net, Inspector, WASI, FFI); file system errors also set resource to the path. Catch on err.code, log err.permission, and the denial is easy to diagnose. A module that fails this way at start-up (for example an ES module that imports a file you did not grant) fails with the same error before any of your code runs.

Source: Node.js API: Command-line options

A few behaviours of the flags themselves are worth knowing before you rely on them:

--allow-fs-read and --allow-fs-write take a path, may be repeated, and accept three forms: (everything), an absolute path, or a path relative to the current working directory. Comma-separated lists stopped working in v20.7.0; passing one prints a warning, so use one flag per path. A path ending in a wildcard matches by prefix, and every character after the first is ignored (/home/.js behaves like /home/). If the path names a directory that exists when the process starts, Node.js appends the wildcard for you, so --allow-fs-read=./data grants the folder and everything below it; a folder that does not exist yet must be written with an explicit / (--allow-fs-write=./cache/) to be usable once it is created.

Source: Node.js API: Permissions, File System Permissions

Two sharp edges are documented. First, some node:fs operations act on an already-open file descriptor rather than a path (fsync, fdatasync, fchmod, fchown and their synchronous variants, plus the equivalent FileHandle methods). They cannot be tied to a path grant, so with the model on they are disabled and throw ERR_ACCESS_DENIED whatever the descriptor’s origin. Second, the constraints section also warns that using existing file descriptors through node:fs bypasses the model. Both are consequences of the same fact: the check happens where a path enters the API, and a descriptor has no path.

Each remaining flag is an all-or-nothing switch for one subsystem. The examples below show what a denial looks like; every one of them was run.

Source: Node.js API: --allow-inspector

With fake.node an empty file that is readable (--allow-fs-read="$PWD/fake.node"), ERR_DLOPEN_DISABLED is the observed result on all three lines; adding --allow-addons changes it to ERR_DLOPEN_FAILED (the file is not a real addon), proving that the permission check is passed. The inspector and WASI attempts report ERR_ACCESS_DENIED with Inspector and WASI on all three lines (observed; for inspector on Node.js 22 this works even though the --allow-inspector flag does not exist there).

Source: Node.js API: --allow-net

When the model is enabled (by --permission or --permission-audit), the process object gains a permission property. Without the flag it is undefined, so feature-detect with process.permission?.has(…​).

permission.has(scope[, reference]) answers "may I do this?" without trying it. The scopes are fs.read, fs.write, child, worker, net, inspector, wasi, addon and ffi. With a reference (a path) it asks about one resource. Observed: without one, fs.read and fs.write print false when only a folder was granted, so the scope-only form behaves as "is everything allowed?".

Source: Node.js API: permission.has(scope[, reference)]

Node.js 24.21.0 prints the same lines. On 22.23.3 the output is identical except drop typeof : undefined, and (observed) asking about net, ffi or an invented scope returns false instead of throwing, so a false there does not prove the scope exists.

permission.drop(scope[, reference]) revokes a permission at run time and is irreversible. The pattern it enables is "read your configuration at start-up, then close the door": load what you need while you still have access, drop it, and a later bug or a compromised dependency cannot read it again. Three details from the documentation matter. Dropping only affects future checks and does not close anything already open (file descriptors, sockets, child processes, workers). You can only drop what was granted exactly: a folder grant is dropped by naming that folder, not a file inside it, and a * grant is dropped only without a reference. And dropping without a reference removes the whole scope.

Source: Node.js API: permission.drop(scope[, reference)]

On Node.js 22.23.3 the call fails with a TypeError because drop does not exist. Observed, not documented: dropping a path that is only inside a granted folder does nothing and has() stays true, so do not assume a narrower drop worked; check with has().

Writing a correct --allow- list by hand is tedious and easy to get wrong. --permission-audit (Node.js 26 and 24.20+) runs the program with the checks in place but without enforcing them: nothing throws, and each violation is published on a node:diagnostics_channel channel instead. The flag does not need --permission and the --allow- flags are optional; you can combine them to audit only the part you have not yet granted. The channels are node:permission-model:fs, :net, :child, :worker, :inspector, :wasi, :addon and :ffi, and each message is an object with permission and resource.

Source: Node.js API: Permissions, Audit Mode

With --allow-fs-read=<app> added, only the write line remained (observed), which is the workflow: run the real workload (start-up, a request or two, the test suite) under --permission-audit, collect the distinct resource values per channel, turn them into --allow-* flags, then switch to --permission. A subscriber only sees what happens after it subscribes, so register it at the very top of the entry point (see Diagnostic Reports, Logging & Observability for the channel mechanism). On Node.js 22 the flag does not exist.

A discrepancy to be aware of, labelled observed: the documentation says that when both --permission and --permission-audit are given, --permission wins and the model enforces. On 26.10.0 and 24.21.0 the program that reads data/books.json without a grant ran to completion with both flags, in either order, behaving as audit mode. Do not rely on mixing the two; use one flag per run and verify with a denial test.

The same settings can live in a Node.js configuration file instead of a long command line. The file is JSON, named node.config.json by default, and permission is a top-level namespace next to nodeOptions, test and watch. The general mechanism (path forms, $schema, nodeVersion, precedence) is in CLI Options, Environment & Config File; here only the permission block matters.

Source: Node.js API: Permissions, Configuration file support

Source: Node.js API: --experimental-default-config-file

On Node.js 26.10.0 this printed an ExperimentalWarning for the config file and then exactly the second half of the earlier probe output (read and write allowed, child and worker denied), because, as the documentation says, the presence of the permission namespace turns --permission on by itself. The details, observed:

The value types follow the flag: path flags take an array of strings, switches take booleans. Keys cannot repeat across namespaces, the parser rejects unknown keys, and the documentation warns that Node.js does not validate or sanitise the file, so never load an untrusted configuration file. Command-line options and NODE_OPTIONS take priority over the file.

Source: Node.js API: --experimental-config-file

npx itself must read the package it runs, so npx --node-options="--permission" some-package fails with a FileSystemRead denial. The documentation gives two fixes: for a globally installed package grant the global node_modules (npx --node-options="--permission --allow-fs-read=$(npm prefix -g)" some-package), and for the npx cache grant the cache directory (--allow-fs-read=$(npm config get cache)). The --node-options form sets NODE_OPTIONS for the processes npx spawns, not for npx itself.

Source: Node.js API: Permissions, Using the Permission Model with npx

The documentation lists constraints and known issues. Each row below is one of them, plus the two I demonstrated.

Source: Node.js API: Permissions, Limitations and Known Issues

With data/link.txt a symbolic link to a file outside data/ and node --permission --allow-fs-read="$PWD/data" limits.mjs, all three lines (26.10.0, 24.21.0, 22.23.3) printed the linked file’s contents and created the database file outside every grant (observed). The sqlite result is a good example of why "the model checks node:fs`" is not the same as "the process cannot touch the disk": a permission-model run that still imports `node:sqlite has an unchecked path to the file system.

Source: Node.js API: --allow-child-process

Run with node --permission --allow-fs-read="$PWD/escape.mjs" --allow-child-process escape.mjs on 26.10.0 the shell created escaped.txt in the working directory even though the Node.js process was granted no write access at all (observed). Without --allow-child-process the same program is refused with ERR_ACCESS_DENIED. A Node.js child, by contrast, stays restricted: a child started with process.execPath that tried to write a file was denied on all three lines (observed).

The practical rules that follow:

The Bookshelf API from this section (an HTTP server on node:http with an in-memory node:sqlite database) needs very little: read its own src/ folder and package.json, and open a listening socket. A repeatable way to arrive at such a list is the audit workflow: run it under --permission-audit, read the reported resources, then enforce exactly those.

Source: Node.js API: Permissions, Audit Mode

Observed on 26.10.0 (with the server started on port 0 so the system picks a free one): the enforced command prints listening <port>, answers a POST /books and a GET /books normally, and omitting --allow-net makes it stop at start-up with ERR_ACCESS_DENIED and permission: 'Net'. A server that writes to a database file would additionally need --allow-fs-write for that folder. Validate a real command by running the test suite under it, and keep it in package.json scripts or the config file so it is reviewed like code. On Node.js 24 and 22 leave --allow-net out; the flag does not exist there, so sockets are always allowed, which is a meaningful difference when you decide how much to trust the model on those lines.

Source: Node.js API: Command-line options (version history of each flag)

Efficient Node.js by Samer Buna (O’Reilly, 2025) mentions the permission model only as something being introduced; it is stable now, and its practical surface is much larger than a single flag: --allow-net (Node.js 25 and later), --allow-inspector, audit mode, process.permission.drop() and the configuration file did not exist or were not settled when it was written. Node.js Projects by Jonathan Wexler (O’Reilly, 2025) does not cover the model at all, so its scripts and servers run with full authority; the patterns it uses (file uploads, child processes, third-party clients) are precisely the places where the model, plus the limits above, is worth considering. Neither book discusses the seat-belt-versus-sandbox boundary, so the safe reading of this page is the official documentation, not an older tutorial’s claim that --permission makes untrusted code safe.