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.
Check the runtime first
Section titled “Check the runtime first”This is the behavior in Knitting 0.1.77, the release these docs describe.
| Worker | What the policy can enforce |
|---|---|
| Node.js threads | Knitting 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 processes | Filesystem 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 threads | Knitting 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 processes | Scoped 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 processes | No 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 the policy
Section titled “Set the policy”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
permissionout. Knitting uses strict defaults withallowImport: true, allowing all import hosts where that control is supported. - Use
permission: {}orpermission: { mode: "strict" }. Knitting uses strict defaults, including the default import hostsdeno.land,esm.shandjsr.io. - Use
permission: "unsafe". Knitting turns off its runtime permission flags and removes inherited Node permission flags from the worker’sexecArgv. 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 });What strict mode starts with
Section titled “What strict mode starts with”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/gcloudand~/.kube; - sensitive POSIX read paths include
/proc,/sys,/devand/etc; - network access, environment access, subprocesses, worker creation, FFI and WASI start without grants;
- object mode allows the three import hosts listed above. Omitting
permissionallows 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.
Grant what the task needs
Section titled “Grant what the task needs”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.
| Field | Requested access |
|---|---|
cwd | Base directory for relative permission paths. |
read / write | Filesystem allow-lists. true requests unrestricted access. |
denyRead / denyWrite | Filesystem exceptions, where the runtime supports deny-lists. |
net / denyNet | Network host allow- and deny-lists. net: true requests all hosts. |
allowImport | Allowed import hostnames. true allows all import hosts; it is not a list of module names. |
env | Environment settings through { allow, deny, files }. files identifies environment files to load. |
run / denyRun | Executable allow- and deny-lists, where supported. run: true requests all subprocesses. |
workers | Whether task code may create more workers. |
ffi / denyFfi | Native-library access. The process transport itself needs native-code access. |
sys / denySys | Deno system-information APIs such as hostname and systemMemoryInfo. |
wasi | Whether WASI is allowed. |
console | Whether 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.
When a process cannot enforce the policy
Section titled “When a process cannot enforce the policy”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.
Keep task code inside the worker
Section titled “Keep task code inside the worker”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.
Runtime-specific options
Section titled “Runtime-specific options”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.