Skip to content

Permissions

The permission option sets the access policy for your workers. You can ask for filesystem, network, environment, import and subprocess restrictions, but what gets enforced depends on the runtime and whether you use threads or processes.

This is the behavior in Knitting 0.1.77, the release these docs describe.

WorkerWhat the policy can enforce
Node.js threadsKnitting passes Node’s permission flags. Filesystem allow-lists and broad capability switches are supported where Node accepts the flags. If required permission flags are rejected, worker startup fails.
Node.js processesFilesystem allow-lists and broad capability switches. Node 22/24 have no network permission control; Node 25+ can deny network access or allow it all, but cannot restrict it to named hosts. Environment, import-host and filesystem deny-lists are not enforced by these flags.
Deno threadsKnitting does not pass a separate Worker.deno.permissions policy in this release. The host’s Deno permissions still apply, but permission does not narrow them for the worker.
Deno processesScoped runtime flags for filesystem, network, environment, import hosts and subprocesses. The shared-memory transport requires FFI access. Knitting does not configure a worker-spawn restriction.
Bun threads and processesNo matching runtime permission controls. The policy cannot restrict task access through runtime flags.
Andromeda threads (experimental)Andromeda decides what workers can access. Leave permission out; setting it causes pool creation to throw. See the Andromeda guide.

For Node threads, the same limits on host lists, environment access and deny-lists apply as for Node processes. These differences matter when a task must only contact one host or run one executable.

Permissions help limit trusted task code. For code you do not trust, use process workers with an OS sandbox. A separate process gives you a memory boundary; the sandbox supplies access controls that the runtime cannot enforce.

Set permissions when you create the pool:

import { createPool, isMain, task } from "knitting";
export const work = task({
f: async (x: number) => x * 2,
});
if (isMain) {
using pool = createPool({
threads: 2,
permission: { mode: "strict" },
})({ work });
console.log(await pool.call.work(21)); // 42
}

There are three common ways to configure permissions:

  • Leave permission out. Knitting uses strict defaults with allowImport: true, allowing all import hosts where that control is supported.
  • Use permission: {} or permission: { mode: "strict" }. Knitting uses strict defaults, including the default import hosts deno.land, esm.sh and jsr.io.
  • Use permission: "unsafe". Knitting turns off its runtime permission flags and removes inherited Node permission flags from the worker’s execArgv. An external sandbox or the host’s Deno permissions may still restrict access.

Strict mode is a useful starting point for your own tasks. Add the access they need, then check that the chosen runtime can enforce it. "unsafe" is also useful when an external sandbox supplies the policy, as in the container example.

The console option controls whether worker console.* calls are forwarded to the host. It defaults to false in strict mode and true in unsafe mode.

createPool({ permission: { mode: "strict", console: true } })({ work });
createPool({ permission: "unsafe" })({ work });

Omitted fields inherit defaults. They are not all denied:

  • reads include cwd, task-module paths and resolved support files;
  • writes are allowed under cwd;
  • the policy denies writes to node_modules;
  • sensitive paths are on the deny-lists, including .env, .git, .npmrc, .docker, .secrets, ~/.ssh, ~/.gnupg, ~/.aws, ~/.azure, ~/.config/gcloud and ~/.kube;
  • sensitive POSIX read paths include /proc, /sys, /dev and /etc;
  • network access, environment access, subprocesses, worker creation, FFI and WASI start without grants;
  • object mode allows the three import hosts listed above. Omitting permission allows all import hosts instead.

Those are the requested defaults. A Node filesystem allow-list does not enforce an exception for .env inside an allowed directory, and Bun cannot enforce the filesystem policy at all. Use the runtime table above when deciding what a task can actually access.

Explicit read and write lists replace their defaults. An empty list requests no access for that field. Relative paths resolve against permission.cwd, or the shell’s current working directory when cwd is omitted.

For example, a Deno process worker can request access to one API and one environment variable:

createPool({
worker: { runtime: "process", processRuntime: "deno" },
permission: {
mode: "strict",
net: ["api.example.com"],
env: { allow: ["API_TOKEN"] },
console: true,
},
})({ work });

Filesystem access still uses the strict defaults in this example. If you supply read yourself, include the task modules and any files needed to load them, as well as the data files your task reads.

FieldRequested access
cwdBase directory for relative permission paths.
read / writeFilesystem allow-lists. true requests unrestricted access.
denyRead / denyWriteFilesystem exceptions, where the runtime supports deny-lists.
net / denyNetNetwork host allow- and deny-lists. net: true requests all hosts.
allowImportAllowed import hostnames. true allows all import hosts; it is not a list of module names.
envEnvironment settings through { allow, deny, files }. files identifies environment files to load.
run / denyRunExecutable allow- and deny-lists, where supported. run: true requests all subprocesses.
workersWhether task code may create more workers.
ffi / denyFfiNative-library access. The process transport itself needs native-code access.
sys / denySysDeno system-information APIs such as hostname and systemMemoryInfo.
wasiWhether WASI is allowed.
consoleWhether worker console.* output reaches the host.

Object mode also accepts mode: "custom". It starts from the strict baseline, but explicit denyRead and denyWrite lists replace the corresponding default denials. In strict mode, those lists add to the defaults.

Process workers check the requested restrictions before starting. An explicit restriction that the runtime cannot enforce causes pool creation to throw. Unsupported implicit strict defaults produce a warning instead.

For example, run: ["git"] requests permission to run Git alone. Deno process workers can express that list. Node’s --allow-child-process grants all subprocess execution, so a Node process pool rejects the scoped request. On Node threads, a nonempty run list enables that broad flag; it does not enforce an executable list.

The same distinction applies to net: ["api.example.com"]: Node process workers reject the host list, even on a Node version with network permission support. Choosing a runtime with scoped permissions or using an OS sandbox lets you keep the intended restriction.

Node process workers need native-code access for the shared-memory transport. Deno process workers need --allow-ffi. A policy that explicitly forbids the transport’s required native access cannot be enforced and is rejected.

Worker permissions do not apply to modules imported by the host. A module can run code as soon as it is imported, before you make a pool call. Calls handled by the inliner also run on the host, under its permissions.

Use importTask when a module must load only inside the worker. The host keeps a typed wrapper without importing or evaluating the task module, and imported tasks stay on worker lanes even when the pool has an inliner.

The node object accepts allowChildProcess, allowWorker, allowAddons, allowFfi and allowWasi. These are broad switches, not scoped allow-lists. The legacy deno.allowRun option also grants subprocess access; prefer the scoped top-level run list for Deno processes.

For the native controls behind these settings, see Node’s permission model and Deno’s permissions.