Skip to content
Tutorials Center
My learning

Topics

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.

NODE
// shell: node --permission --allow-fs-read=./data --allow-fs-write=./out app.js

Try it

Node.js Everything denied, then reads granted

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.

Node.js Asking the permission API

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

NODE
// shell
node --permission [--allow-fs-read=<path>] [--allow-fs-write=<path>]
     [--allow-child-process] [--allow-worker] [--allow-addons] [--allow-wasi] <script>
NODE
// 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 readFileSync of a file next to your script fails until you grant that path (the first example shows ERR_ACCESS_DENIED for both reading and writing).
  • Paths are matched as prefixes of resolved absolute paths. Granting a directory grants everything beneath it. Granting ./data is relative to the current directory when Node starts.
  • --allow-child-process weakens 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); --permission became the stable spelling in 22.13 and 23.5.