Node.js Reference ยท CLI Flags
Node.js --permission flag (permission model)
Reference for node --permission and the --allow-fs-read, --allow-fs-write, --allow-child-process and --allow-worker flags that restrict what code can do.
--permission turns on Node.js's permission model. Once enabled, the process starts with almost nothing allowed: no file reads or writes, no child processes, no worker threads, no native addons. You then grant back only what the program needs with --allow-* flags. An action that is not allowed throws an error with the code ERR_ACCESS_DENIED.
It is a seat belt, not a sandbox. It reduces the damage a compromised dependency or a path-handling bug can do, but it does not make untrusted code safe to run.
// shell: node --permission --allow-fs-read=./data --allow-fs-write=./out app.js
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
// shell
node --permission [--allow-fs-read=<path>] [--allow-fs-write=<path>]
[--allow-child-process] [--allow-worker] [--allow-addons] [--allow-wasi] <script>
// in code, only when the flag is on process.permission.has(scope, reference?) // boolean
| Name | Description |
|---|---|
--permission |
Enables the model. Everything below is denied unless granted. |
--allow-fs-read=<path> |
Allows reading a file or directory tree. * allows everything; the flag may be repeated, or take a comma-separated list. |
--allow-fs-write=<path> |
Allows writing, with the same path rules. |
--allow-child-process |
Allows spawn, exec, fork and friends. |
--allow-worker |
Allows worker_threads. |
--allow-addons |
Allows native addons. |
--allow-wasi |
Allows WASI instances. |
Returns: nothing. process.permission.has('fs.read', path) reports whether an action is allowed; process.permission is undefined when the model is off.
Errors: a denied action throws ERR_ACCESS_DENIED; the error carries permission (for example FileSystemRead) and resource properties.
Usage notes
- Default is deny. Even
readFileSyncof a file next to your script fails until you grant that path (the first example showsERR_ACCESS_DENIEDfor both reading and writing). - Paths are matched as prefixes of resolved absolute paths. Granting a directory grants everything beneath it. Granting
./datais relative to the current directory when Node starts. --allow-child-processweakens the model. A child process can be started without the restrictions unless you pass them again, so Node prints a security warning. Avoid it unless the program must spawn tools.- Not a sandbox. Network access is not restricted by the flags covered here, and native addons or a bug in V8 or Node can bypass the checks. Use containers or separate users for real isolation (vm is not a sandbox).
- Good for hardening scripts and CI jobs that only need a couple of directories: build tools, report generators, linters you run on third-party code.
- The entry script is implicit. You do not have to grant read access to the file you pass to
node; only the other files it opens at run time need a grant. - Version notes: originally
--experimental-permission(Node.js 20);--permissionbecame the stable spelling in 22.13 and 23.5.