fs patching and FUSE, the browser’s sandbox,
and how a call is cancelled. Cloudflare Workers have their own
limits, and limits every host
shares are on Limits and the shell page.
Node
Node versions
@struktoai/mirage-node needs Node ^22.20 || ^24.12 || >=25. The core and
browser packages, run under Node, need 20.18.1+ on 20, or 22+.
patchNodeFs misses ESM imports
patchNodeFs(ws) routes fs calls on mounted paths into the workspace by
swapping the functions on CommonJS fs and fs.promises. An ESM named
import, import { readFile } from 'node:fs/promises', is bound when the
module loads, so it bypasses the patch and reaches the real filesystem.
Synchronous calls (readFileSync) refuse a mounted path either way, since
the workspace answers asynchronously.
Instead:
- Call
ws.shell(...)orws.vfsdirectly, from ESM or CommonJS. - Mount the workspace as a FUSE folder, so every
fscall goes through the kernel. - Keep the code that reads the files in CommonJS,
require('fs').
A FUSE folder is served on the process’s event loop
A synchronous call on the folder from the process that mounted it, such asreadFileSync or execFileSync('cat', ...), blocks the loop that must
answer it, and the mount hangs. Use async fs calls and async child
processes, or own the mount from a child process. See FUSE.
Browser
A browser workspace runs inside the page, with no kernel, no subprocesses and no Nodefs. Every command runs in-process, and python3 runs on
Pyodide.
- No FUSE. A page cannot mount a folder: the browser
Workspacetakes plain mounts. Usews.shell(...)andws.vfs. - OPFS quota and eviction.
OPFSVFSstores files under the browser’s per-origin quota. Set itscapacityso a write fails withDisk quota exceededbefore the browser’s own quota does;navigator.storage.estimate()shows the room left. The browser may clear an origin under storage pressure unless the page callsnavigator.storage.persist(). - CORS. A VFS that calls a third-party API from the page fails unless
that API allows the page’s origin. Slack and Discord take a
proxyUrlto a backend that adds the token; S3, R2 and GCS take presigned URLs; Notion, Box, Dropbox and Google sign in from the page with OAuth. - Pyodide caches files for a run. A file Pyodide read stays cached for
that run, so an outside edit shows on the next run. Without a worker and
either
SharedArrayBufferor Mirage’s service worker,python3exits 127; see worker and browser setup.
Building an unsupported VFS throws an error.
Cancellation
ws.shell(command, { signal }) cancels a call. A JavaScript promise cannot
be cancelled, so:
- TypeScript fires the signal, gives the line 250 ms to settle, then rejects
with an
AbortErrorwhosecauseis the signal’s reason. - A step that ignores the signal, such as a custom handler or a backend call
with no signal, can run on after that. Its output is dropped and it cannot
change
$?, but a write it completes still lands. Built-in commands check the signal between operands, so they start no new read or write. - Long commands yield to the event loop as they go, so timers and I/O keep running, but a single synchronous step, such as a large regex match, holds the thread until it returns. To stop arbitrary code hard, run the workspace in a worker or a separate process.
- A command timeout is a normal result (exit 124), not a cancellation.
- The signal does not reach background jobs. Stop them with
kill.