countinghouse

Security model

This document describes the isolation and trust model countinghouse actually implements today — not the isolation model a multi-tenant runtime would ideally have. Where the two diverge, we say so plainly. An overstated isolation claim is a worse security posture than an honestly-scoped one: it invites integrations that assume guarantees the runtime doesn’t provide.

Threat model

countinghouse runs third-party npm packages (“device modules”) as tools callable by MCP clients and agents. The runtime treats these modules as semi-trusted, not sandboxed-for-arbitrary-code: each module executes with the privileges of the Node.js process’s OS user, narrowed by an in-process sandbox that is a strong barrier, not a hard boundary (see below). There is no attempt to run modules from parties the platform operator hasn’t reviewed.

Since 8.0.0 each module runs inside its own worker_threads.Worker by default (lib/lean-worker.js, spawned from lib/module-manager.js’s loadModuleByWorker). --no-workerThread runs modules in the main thread instead; that mode is for debugging modules and has no sandbox at all (single-thread mode). A worker gives:

What the module sandbox adds, and what it does not stop

The module sandbox is delivered in four parts. Part 1 (foundation, design in superpowers/specs/2026-10-15-module-sandbox-foundation-design.md) and part 2 (file broker and virtual paths, design in superpowers/specs/2026-10-17-module-sandbox-fs-broker-design.md) are what this document describes. They add layers on top of the worker boundary, enforced inside the same process as the code they restrict:

It is a strong barrier against accidents, buggy or exploited dependencies, and ordinary malware. It is not a hard boundary against code written specifically to defeat it.

One overlooked internal API, or one V8 bug, gets past the in-process layers. Each layer below says what it stops and what it does not.

Boundary checks run on intrinsics captured before module code loads. Module code shares the worker’s realm with the checks that bound it, and can replace a method of String, Array, Set, Map, RegExp or Function, or a property of a shared built-in module. So the lockdown’s checks (which built-in may load, whether a path given to CHUtil.loadFile or the reduced module.createRequire is inside the module’s root, whether a host is granted) call only functions taken when their file loaded, before any module code: never a method looked up when the check runs. The file broker’s own checks and its loader hook (lib/fs-broker) follow the same rule in the next change; until then a require of a file outside the root can pass the loader hook with such a method replaced, and the broker’s read of it answers ENOENT. A guard hands a call on to the original it wraps through a Reflect.apply taken at load, never the original’s own call or apply, which a module could have replaced to receive it. Live lists a check consults (the allowed built-ins, the loopback names) are private to their file, exported only as frozen copies. The intrinsics themselves are not frozen (that breaks common packages). What Node’s own loader reads from objects a module can reach is fixed at the lockdown instead, in audit and enforce: every function of the path, path.posix, path.win32 and url exports, URL.prototype’s accessors and methods, and module.isBuiltin are non-writable and non-configurable, so a module cannot show the loader or a check one path and have another one used. A module that patches path, url or URL runs only under off.

Known limits of this rule:

Modes. --moduleSandbox off|audit|enforce, default audit. The sandbox needs worker mode; without it the mode is off. countinghouse 8 needs Node 22.16 or later. Below 24.15 a compatibility shim routes require.resolve through the sandbox’s hooks (lib/resolve-shim.js); multi-tenant hosting of third-party modules should run 24.15 or later, where Node’s own hook covers it.

  off audit (default) enforce
Virtual paths, file broker, bridge yes yes yes
Link rules, main-thread protection yes yes yes
Reads outside the namespace pass through pass through, logged refused
Writes outside the module’s own area (outside the namespace, /app, r paths) pass through refused (EACCES), recorded refused
Disk quota not counted logged enforced
Lockdown, resource limits, clean environment no yes yes

On Windows a module’s files carry a drive (#195): the module sees them, its current directory and its stack frames as <V>:\app\..., V a drive letter the host does not have, picked once per process, because Node there loads a file only by a URL with a drive (file:///<V>:/app/...). The runtime names them /app/..., and the file broker maps <V>:\app, <V>:\data and <V>:\tmp to /app, /data and /tmp, so every rule above applies on Windows as it does elsewhere. With no free drive letter, --moduleSandbox enforce refuses to start on Windows, saying so.

On Windows, a module’s declared host paths are not available yet (#204): a declared root is a host path, which there carries a drive, and the broker takes every drive-qualified path as outside the namespace. Under enforce such a path is refused (ENOENT): it fails closed. The module gets its own /data and /tmp.

Under audit a module changes nothing outside its own area (Matt, 2026-11-15). Its own area for writes is its /data, its /tmp and what it declared rw. Every write-class operation aimed anywhere else is refused EACCES and recorded as a denial: an open for writing, a create or truncate, writeFile, appendFile, mkdir, rmdir, rm, unlink, rename or link with either end outside (a hard link’s source included), a symlink made outside, chmod, chown, utimes, truncate, and copyFile or cp to an outside destination; writes to /app and to a path declared r too. A symlink made inside the namespace that points outside it is refused EPERM, in every mode, as before.

Only enforce hides files. Under audit and off reads outside a module’s namespace pass through to the host, except the always-denied set and the protected paths above: under audit a module can read any other file the OS user can – the operator’s project directory, the current directory, ~/.npmrc, ~/.ssh – and each read is logged. So don’t run untrusted packs under audit on a machine that holds secrets: use enforce. In audit every check runs, a violation is logged once per (module, rule, target), and a read goes ahead. In enforce a violation is blocked with the error Node itself would throw (ENOENT, EROFS, ENOSPC, ERR_ACCESS_DENIED, MODULE_NOT_FOUND) and logged. Resource limits apply in audit as well, because logging a runaway allocation does not stop it. off still runs the broker: modules see the same virtual paths in every mode, and every file call is a hop to the main thread (measured cost).

1. Worker lockdown (lib/module-lockdown.js, run once per worker before any module code). Stops:

Each override is non-writable and non-configurable. net, http and the like stay usable until parts 3 and 4; the first require of each is logged (as “uses”) so operators learn which modules will need permissions.

2. The file broker and the virtual namespace (lib/fs-broker/). Before any countinghouse or dependency code loads, the first statements of lib/lean-worker.js replace every method of the worker’s fs, fs/promises and FileHandle.prototype with locked versions that send each call to the main thread. There one broker per module checks it and runs it with Node’s async fs. Synchronous calls wait on shared memory; the main thread never blocks. The list fails closed: a key a later Node adds throws until it has been reviewed. Watching (fs.watch, watchFile, promises.watch) answers ERR_FEATURE_UNAVAILABLE_ON_PLATFORM.

A module sees its own namespace, in every mode:

Virtual path Host path Access
/app the module’s install directory read-only: EROFS under enforce, EACCES under audit
/data <moduleDataPath>/<name>/data read-write, quota, kept across restarts
/tmp <moduleDataPath>/<name>/tmp read-write, quota, emptied when the worker starts
each declared path, e.g. /var/log/app the same host path r or rw as the operator’s policy narrows it; no quota

<name> is the package.json name the main thread verified. A load whose request name differs from it is refused in every mode (MODULE_NAME_MISMATCH), so code cannot be loaded under another module’s name to get its policy entry and data. __filename, __dirname, require.resolve, require.cache keys, import.meta, stack frames, process.cwd() (/app) and os.tmpdir() (/tmp) are virtual, and so are paths in results and errors. Ancestors of a root (/, /var) answer as read-only directories that list only the way to the root. A declared path can never cover countinghouse’s own directories (the install directory, --modulePath, --moduleDataPath, the auth and device-config paths, the policy file, the --remoteCredentials file) or an ancestor of one: such a declaration is refused in every mode and logged at spawn.

Nor can a writable declared path hold a name on a path countinghouse runs through:

Whoever can replace a link on such a path, or a directory one of their targets passes through, chooses what the next start runs, or where it keeps its modules and data. So a declaration with rw access is refused when it is the directory of such a name or a directory above it, however the declaration spells it; a read-only one is kept. Under --hardened the names are found before the server restricts itself; a server put under Node’s permission model another way (node --permission by hand) cannot look for them, and refuses to start. Two things this does not see: a Linux bind mount of a directory that holds such a link (the mount is another name for it that no path comparison shows; the protected directories above share this), and a Windows mount point given by volume GUID.

Beyond declarations, every path in those directories – every module’s code (--modulePath and each --loadModule directory) and data (--moduleDataPath, also while a module is being validated), the local store, the auth and device configuration, the policy file, the --remoteCredentials file (which says where each credential may be sent) – and in ch-local’s home (the directory of --settingsFile: its settings, the daemon’s session secret under run/, the launcher, the pack records) is refused to a module’s reads and writes under audit and enforce (EACCES, recorded), however it is named: directly, through .., a symlink or a hard link to the settings files. The policy file and the --remoteCredentials file are refused by their paths, not by identity as the settings files and the auth configuration are: a hard link to one of them, under a name outside these directories, is another path and is not refused. A module cannot make one (a link with either end outside its roots is refused, and under enforce a module whose /data or /tmp holds one does not start); the limit is a link that an operator, or other software on the machine, left where a module may read. A pack loaded in place may come with a credentials file of its own, read when the pack is loaded (lib/packs-in-place.js): that file is no option of the runtime’s, so it is not a protected path by itself; ch-local writes it under run/ in its home, which is protected as a whole. The one exception is the module’s own /app, /data and /tmp, by their real paths at spawn. A listing never shows them, and neither they nor any directory above them can be renamed or removed. The install directory is the exception: it is countinghouse’s public code and stays readable under audit, except its top-level dot entries (.git, .env*, .npmrc, .claude, any other) and a top-level auth.json, which are refused to reads and writes under audit and enforce as the rest is. Keep no other secrets in it.

For each call the broker translates the virtual path, decides by mode, then checks the host: the real location must lie inside its root, compared with roots resolved at spawn. Under enforce every opened descriptor is then verified (its device and inode, and on Linux /proc/self/fd) against that location, so a path swapped for a symlink between the check and the open is closed and answered ENOENT. Mutating calls take a per-module lock exclusively and every other call shares it, so a module cannot race its own checks. The broker caches directory real paths for up to 1 s; every mutating call clears the cache first, and opened descriptors are still verified without it.

In every mode: link() works only within one writable root; symlink() takes only a relative target with no .. segment, and only when the target really leads inside its root, following any link on the way (an absolute target, a .., or a target that leads outside is EPERM); chmod strips setuid, setgid and sticky bits; a cross-root rename answers EXDEV. Under enforce a module whose /data or /tmp holds a symlink with an absolute target, or a hard link to a file that also has a name outside its /data and /tmp, does not start until the operator removes it (the log names the entries). The disk quota (diskMb, diskEntries, one pool for /data and /tmp) answers ENOSPC under enforce.

The main thread is protected in every mode: the thread pool is raised to 16 unless the operator set UV_THREADPOOL_SIZE, brokered operations in flight are capped globally and scheduled round-robin across workers, each worker has a queue of 4096 (EMFILE past it) and at most 256 descriptors, and a transfer is at most 16 MB, with readFile served in chunks. A brokered call that takes over 30 s answers ETIMEDOUT.

3. The bounded loader (lib/fs-broker/identity.js). Node’s loader reads files through the same fs, so the loader hooks decide that traffic. Module code resolves to virtual file:///app/... URLs. Before the worker’s set-options, while only countinghouse’s own boot runs, it reads only its code roots; anything else it touches is answered ENOENT and logged once as countinghouse’s own, in every mode. From set-options on, every resolve is bounded, whoever the parent is: module code reaches only its own root, and countinghouse’s code reaches only its own code roots plus the module root. That closes module.parent.require, require.cache[...].require, Module._load, and the vm.Script dynamic import() referrer as routes to files, which part 1 left open. The original fs is used only for the loader’s lookups under those roots and for the one file being loaded; everything else goes to the broker with the module’s rights. Under enforce the loader’s own lookups (Module._stat, package.json reads) answer “missing” outside those roots too.

countinghouse’s code roots are its own entries and the package directory of each package in its dependency closure, found the way Node finds them, so an npm install that hoists them into the project’s node_modules works. A dependency installed as a symlink (pnpm, a linked node_modules) is a root under both the name Node looks it up by and its real path. They are never a whole node_modules: modules are npm packages too, and may sit beside countinghouse’s dependencies. A module root is subtracted from the list.

countinghouse installed under /app is refused at startup under --workerThread (exit 2). Precisely, code countinghouse itself loaded may not live under /app: Node keys loaded code by path, so it would share entries with modules’ /app files, and a module could be handed countinghouse’s own module objects. Modules and data under /app are fine.

4. Declared permissions and the operator policy. A module declares countinghouse.permissions (fs, net, env, limits) in its package.json; the operator’s --modulePolicy file can only narrow that, never widen it (a wider entry is reported and ignored). fs (outside paths, r or rw each), env and limits take effect; so does the host check on CHUtil.request described below. The rest of net is parsed, validated and logged as effective permissions, and takes effect when parts 3 (HTTP broker) and 4 (TCP/TLS relay) ship.

5. Load-time checks and the validator (lib/module-tree-check.js, countinghouse-validate). A module must be self-contained (every dependency, through the whole tree, resolves inside the module’s directory), must not contain native code (.node, binding.gyp, "gypfile": true), and must have valid permissions; install scripts are warned about. In enforce a failing module is refused with MODULE_SANDBOX_REFUSED; in audit the failures are logged and the module loads. This is a structural check of what is on disk at load time, not a review of what the code does.

6. Resource limits, restart and suspend. heapMb (V8 resourceLimits, with a 64 MB young generation and a 4 MB stack beside it), externalMb (the main thread polls the worker’s external memory and terminates it over the limit) and maxBlockMs (the main thread pings the worker and terminates it if a ping goes unanswered for that long), checked every second or twice per maxBlockMs if that is shorter, each with a 256 / 256 / 10000 default ceiling. Time a worker spends waiting on a brokered file call does not count as blocked. A worker-to-main message rate limit (--moduleMessageRate, default 2000/s) answers excess messages with RATE_LIMITED instead of killing the worker; file traffic has its own budget (layer 2). Every message a worker sends the main thread, the file bridge’s included, crosses as an envelope of serialized bytes whose length the main thread reads before it decodes anything: over --maxOutputBytes plus 64 KiB (16 MiB plus 64 KiB on the file bridge) it is refused in the worker (MESSAGE_TOO_LARGE, or EINVAL for a file call), and under audit and enforce the lockdown pins the worker’s ports, so module code that patches MessagePort.prototype is never handed one. A message that is not an envelope, or one over the cap, is a tampered worker’s: the main thread ends the worker (a bridge call is answered EINVAL and reported, and the worker is ended too). Module code gets no port by any other route either: the runtime’s port callbacks run in a scope of their own (lib/port-scope.js), and the lockdown leaves ports out of process._getActiveHandles() and _getActiveRequests(), async_hooks.executionAsyncResource() and an async hook’s init, and pins Node’s own stdio port as well. What remains rests on those: Node decodes a posted message on receipt and, when a worker ends, every message it had queued, so a worker that did hold a port could have any number of messages decoded (20 of 5 MB each, all decoded after terminate(), measured on Node 24.21; removing the listeners or closing the main side’s port does not stop it), and that serialized data lies outside the worker’s heap limits. Under off there is no lockdown and the bound is cooperative only; a direct peer channel between two workers is not enveloped. A worker that ends unexpectedly is restarted after 1 s, then 2 s, and suspended on the 3rd exit within 10 minutes (the code caps the delay at 60 s, which the current threshold never reaches); calls get MODULE_RESTARTING or MODULE_SUSPENDED while the tools stay listed. A deliberate reload or unload fails its calls in flight with MODULE_RELOADING or MODULE_UNLOADED. Why a device is missing is told only to a caller that passes the access check for it, so a key without access cannot learn whether a device was ever hosted. When a worker ends, its file operations in flight answer EIO and its descriptors close; a per-name lifecycle lock makes the next start (and an uninstall) wait for them. This bounds memory, blocking, disk use and crash loops. It does not bound CPU use that yields to the event loop, or network traffic.

A module’s stdout and stderr are bounded the same way. Under audit and enforce the lockdown gives module code runtime-owned streams for process.stdout, process.stderr and process.stdin (fixed getters), points console and process._rawDebug at them, and Node’s own stdio streams, which hold its port to the main thread, are never handed out (assigning process.stdout is refused: a TypeError in strict mode, a no-op otherwise). What a module writes crosses as messages, as lines: each stream has 256 KiB a minute of what is written, each line charged its <module>: prefix, its bytes and its newline (counted in the worker; the main thread counts again, with twice that as a backstop, since the two sides’ windows do not line up), past which lines are dropped, output that could not be sent is counted with them, and one line a minute says how much (<module>: N bytes of stdout dropped); each line is cut at 8 KiB, stripped of control characters other than tab, the line separators and the bidi controls, and written prefixed with the module’s name, to stderr under --stdio (stdout is the MCP channel there). The worker’s own log (countinghouse’s code in the worker) crosses as records under a budget of its own, 1 MiB a minute, each record charged 256 bytes plus its fields, each field cut at 8 KiB and cleaned the same way and the module named by the main thread, in every mode. Under off a module’s output goes to the process’s streams as before, unbounded.

Uninstall. POST /uninstall-module {name, keepData} (admin key) removes the registry entry and deletes <moduleDataPath>/<name> unless keepData, never following links. It refuses while the module is loaded, restarting or suspended, and never removes the module’s code under --modulePath. Unload, restart and reload never delete data.

7. --hardened. Re-launches the server under Node’s permission model (--permission) with read access to the install directory, --modulePath, --moduleDataPath and the configured config files, and write access to --modulePath, --moduleDataPath (and the SQLite auth directory). This applies to the whole process, main thread included, so it limits what any module can reach on the host even under audit, but cannot separate a module from countinghouse’s own data in the directories the process may read. Every module must live under --modulePath. Node 24 has no network permission; Node 26 has one, and --hardened passes --allow-net there (experimental in Node 26), so on every supported Node the network is unrestricted under --hardened until the network broker, and outbound network is left to the OS. A systemd unit example is in the example below.

The local store (--store local)

--store local keeps what the runtime held in Redis in files under --storePath (default <moduleDataPath>/../store, outside every module’s namespace) and in memory, and opens no socket of its own. The directory is the owner’s only (0700) and each file too (0600); every write is a temp file renamed into place under <storePath>/.lock, merged by key, so several processes may share the store. No file under it holds an API key: metering without --meter records calls in memory only, and with --meter metering.json keeps each key’s balance and free calls under the key’s fingerprint (a full, domain-separated sha256). The seeding command, countinghouse-meter, reads the key from COUNTINGHOUSE_SEED_KEY, never from its arguments, and prints only the fingerprint.

In the single-identity profile (--store local --stdio without --authConfigPath or --authProvider) no auth file exists. The one key is made at start, read-only, and no file holds it: the runtime never prints, logs or writes it, keeps it out of the options a worker receives, and leaves it out of every answer the auth provider gives, a refusal of another key included. Module code never sees it: since R2-1 a module gets the caller as its opaque id (ctx.caller = {id, isAdmin}), and a composing module’s binding stays on the main thread. Every loaded module runs as that identity, which is not admin. The runtime’s caller id for it comes from the identity secret, <storePath>/.identity-secret (0600, in the always-denied set; the store directory is a path no module may declare), and the fixed source local, so it survives a restart while the key changes per process. A multi-tenant --store local server keeps its secret under <moduleDataPath>, so moving to the local store changes no user’s id.

The operator’s ceiling (guarding settings)

An operator can bound what anyone on the machine may loosen, through a conversation or the ch-local command, with an optional, machine-wide file: /etc/countinghouse/ceiling.json on Linux and macOS, %ProgramData%\countinghouse\ceiling.json on Windows.

{"version": 1, "maxOutputBytes": 16777216, "requestTimeout": 60000,
 "forbid": ["moduleSandbox", "autoUpgrade"], "packs": ["ci-failure-triage"],
 "conversation": false}

Every key but version is optional: maxOutputBytes and requestTimeout lower the hard bounds (requestTimeout in whole seconds, as milliseconds: the runtime takes seconds, so any other value fails closed); forbid refuses loosening the sandbox or turning automatic upgrades on; packs is the operator’s allowlist of packs: when present, only those packs ever load, at start, in place and on install, whatever settings.json or the history say, and installing another is refused; "conversation": false refuses every loosening asked for in conversation, so no dialog is ever shown and each ends at the terminal command (below). A value above it is SETTING_ABOVE_CEILING, a loosening it forbids SETTING_FORBIDDEN_BY_CEILING. A tightening of the value the runtime runs with is never refused by it. A change that only lowers a stored value, and is still above both the ceiling and what the runtime runs with, is refused (SETTING_ABOVE_CEILING): it would put a value above the ceiling in settings.json for the next start. For the two caps the settings tool reports, and judges a change against, what the runtime runs with (with nothing stored, what it started with: the ceiling may have bounded the start), not the stored default. What it writes to settings.json without the user’s confirmation never exceeds what the file yields already (its stored value, else the default), and is above the ceiling only when it lowers what the file yields: a runtime started above the default by a flag cannot have conversation raise the file toward its start value. A lower value than what runs that may not be written applies to this start only, and is recorded as that. It is read once per process, and again when the file changes.

It is trusted only when an ordinary user cannot have written it: on Linux and macOS the file is not a symbolic link, and it and every directory up to / (by real path) are owned by root and not writable by group or others; on Windows the directory and the file are owned by, and writable only by, Administrators, SYSTEM or TrustedInstaller (by SID), and ProgramData is the system’s known folder, not the caller’s %ProgramData%. A directory made under ProgramData inherits a write right for Users, so the operator removes it (icacls "%ProgramData%\countinghouse" /inheritance:r /grant Administrators:F SYSTEM:F Users:RX). Both must stay readable by every user (0755 and 0644 on Linux and macOS). A file that exists and fails any check, or holds anything else, fails closed: every loosening is refused (SETTING_CEILING_UNTRUSTED), naming the file and why; so does a countinghouse directory an ordinary user could have made, even with no file in it. No directory and no file: the hard bounds apply. On Windows the ACL is read by the PowerShell in the Windows directory, started by its full path with a minimal environment. Not checked, because each needs root or an administrator to set: macOS extended ACLs (chmod +a). A Windows conditional access rule, which the ACL’s rules do not list, fails closed.

On Windows, --hardened cannot verify the ceiling, so no loosening is allowed: the permission model refuses the PowerShell the ACL check needs, the ceiling reads as one that cannot be trusted, and it fails closed. (The identity secret is checked by the --hardened parent before it relaunches under the permission model; the child takes that same file only, unchanged.)

In a shared runtime, every call of a session is held to the tighter of the runtime’s default and the ceiling, whether or not the session set a value of its own, and also under a ceiling that turns conversation off or forbids changing the setting. ch-local’s start clamps the defaults it passes to the ceiling; a runtime started another way, with a default above it, still doesn’t serve above it.

A session’s per-call checks don’t read the ceiling each time: lib/session-settings.js takes its last read again for up to 1 s, on a monotonic clock. A ceiling the settings tool re-reads replaces it at once.

The shared runtime reads the ceiling when it starts serving sessions, and checks it again on a timer:

So a ceiling lowered on disk bounds a session’s calls within about 10 s on Linux and macOS and within about 5 minutes on Windows, without anyone calling the settings tool. Until it is read again the calls are held to the operator’s previous ceiling: never beyond it, and never to the runtime’s default alone.

A --stdio runtime does not read the ceiling when it starts or watch it: its calls are bounded by the ceiling only once the settings tool or a control message from ch-local has read it. Under ch-local that changes nothing, since start has already clamped the flags it passes. The ceiling is a rule for a runtime ch-local installed and starts; a --stdio runtime started by hand with flags above it is not held to it before that first read.

Two limits. <home>/history.jsonl is a record for the user, not a security boundary: the user can write it, so nothing the ceiling enforces rests on it. And ch-local reads the ceiling with the runtime installed under its home (app/node_modules/countinghouse): whoever can replace that code is beyond any ceiling, as they are beyond the runtime itself.

Confirming a loosening in the client’s dialog

A loosening asked for in conversation could come from a prompt injected through a tool’s result, not from the user. So countinghouse_settings never applies one on the model’s word. A raised maxOutputBytes or requestTimeout, or a pack turned on, is either confirmed by the user in their client’s own dialog (an MCP elicitation form) or refused with the ch-local command the user runs at a terminal. Loosening the sandbox or turning on automatic upgrades is terminal only.

A dialog is shown only when all of these hold:

The dialog has one checkbox and no default. Its text is built from the change alone, naming the current value (and a pack’s version, from packs.json); no text from the model appears in it. The model’s arguments cannot carry the answer: requestState and the user’s answer are read only from the request’s own parameters. requestState carries only a random nonce and an HMAC, under a key held in memory for this start, binding the MCP session and the exact change; it is single use and expires after 120 s. Only an explicit accept applies the change. The client’s conditions, the current value, the ceiling and the decline lock are all checked again first, the history line is written before the change, and settings.json is never written: the change ends when the client restarts countinghouse. What was applied, or could not be, is told to the user as a notice (on the next result of any tool, and as an MCP notifications/message).

What this does not cover:

In a shared runtime (one runtime serving several of a user’s client sessions) all of this is each session’s own, for the two caps:

A change for all sessions. In one session the user may ask to change one of the two caps for every session; the model’s call then says scope: "all-sessions". It is a global change, as one made at a terminal is:

A tightening needs no dialog. A loosening always needs one: the asking session’s own (it spends one of that session’s three and counts in the user’s window), whose text names all sessions and says the change holds after a restart. Its state confirms that change only: a dialog that said “this session” confirms nothing for all sessions, and the other way round. It is held to the operator’s ceiling as any loosening is. For a raised output cap the validators grow first, which changes nothing; then, under one lock and with no wait in it, everything is checked as it is then (the session, its lock, the ceiling, the default in force, the file as the dialog saw it), the file is written, and the value is put in force. So a change that cannot be stored is not in force, and a terminal change made meanwhile is never written over. The session that asked gets the value too: its own lower value for that setting goes, and it is told; another session’s own tighter value stays. What is written without a dialog never raises what the file yields (a runtime started above it by a flag, or a tighter value stored for the next start): such a value holds for every session until the runtime restarts. Every other setting stays the terminal’s.

Across a runtime restart. The runtime keeps nothing of a session on disk. After every change it tells ch-local’s daemon the session’s whole state, which is its own values, its locks, its dialogs left and the kinds of which it has left one dialog unanswered (two of a kind lock that kind): no key, no user’s name, no nonce, no pending dialog. A dialog open at a restart is lost: its state was under a key the new runtime does not have. It is counted for its session as one left unanswered, since a dialog open when the state is told is told as that (as a lock, when it is the second of its kind), and an answer corrects it. So a restart hands a session no dialog back. It is not counted in the user’s window, which counts across sessions: after a restart with a dialog open that count is one short. The daemon keeps the table in memory and hands it to the next runtime before that one listens. Its shape is checked by the daemon when it is told and twice by the runtime when it comes back (the restore, then each row at its session’s resume), and what it says is taken only this far:

The row’s word that a loosening was confirmed is the daemon’s: no dialog is shown again for it. So whoever can speak as the daemon on the runtime’s control channel can raise a session’s cap as far as the ceiling, with that session’s client agreeing, and no dialog. The channel is the pipe from the process that started the runtime, which is ch-local, the user’s own; a module has no way to it.

A --stdio runtime has the one store and the one start it always had, and is outside the window.

A module’s question to the user (ctx.ask)

A module’s handler may put a question to the user of an MCP client (ctx.ask; an MCP elicitation, answered on a retry of the call). What bounds it:

What this explicitly does NOT provide (accepted gaps and limits)

The following are known, accepted, and not hidden by the layers above. The sandbox isolates modules from each other and from tenants’ data inside one process; it does not isolate countinghouse from the host. Run it as an unprivileged user in a container with limits and the default seccomp profile: deployment.md gives the posture, a reference setup, and the short list of what the in-process sandbox cannot give.

Remote MCP servers: a module cannot choose where a credential goes

A module may declare one remote MCP server (countinghouse.remotes) and call it with ctx.call('remote:<name>/<tool>', args). The connection is the main thread’s, not the module’s (spec: docs/superpowers/specs/2026-11-11-rc1-min-remote-mcp-design.md):

Cancelling a call in flight

A client can cancel a call while it runs (MCP completeness section 13): on HTTP a 2026-07-28 request’s POST closing before its answer, on stdio and a shared runtime’s session notifications/cancelled by request id. A legacy HTTP request’s disconnect changes nothing.

Current mitigations inventory

These are real, and worth being specific about rather than waving at “we have security measures”. The sandbox layers above come first in effect; these are the checks that predate them and still apply:

Hardening with systemd

Node 24 has no network permission, and on Node 26 --hardened passes --allow-net, so under --hardened outbound network is left to the OS. A unit along these lines (adjust paths, addresses and ports) gives the process a read-only file system apart from its module and module-data directories, no new privileges, a private /tmp, a memory ceiling, and a network filter. The filter (IPAddressDeny/IPAddressAllow) applies to packets in both directions for the whole service, not only outbound connections: remote MCP clients reaching the listen port are dropped unless their networks are allowed, and a local DNS resolver must be allowed if hostnames are used anywhere (Redis URL, module hosts):

[Service]
ExecStart=/usr/bin/node /opt/countinghouse/framework.js --workerThread --hardened --moduleSandbox enforce --modulePolicy /etc/countinghouse/policy.json --modulePath /var/lib/countinghouse/modules --moduleDataPath /var/lib/countinghouse/module_data --authConfigPath /var/lib/countinghouse/auth/auth.json
WorkingDirectory=/var/lib/countinghouse
User=countinghouse
ProtectSystem=strict
ReadWritePaths=/var/lib/countinghouse/modules /var/lib/countinghouse/module_data /var/lib/countinghouse/auth
NoNewPrivileges=yes
PrivateTmp=yes
MemoryMax=2G
IPAddressDeny=any
# Redis, and loopback clients
IPAddressAllow=127.0.0.1
# Networks your MCP clients connect from
#IPAddressAllow=10.0.0.0/8
# Local DNS resolver (systemd-resolved)
#IPAddressAllow=127.0.0.53
# CouchDB and operator-approved module hosts, by address
#IPAddressAllow=192.0.2.10

The server binds 127.0.0.1 unless --bindAddr is given; for remote MCP clients add, for example, --bindAddr 0.0.0.0 to ExecStart, and give --debugKey with --debug (without it, --debug refuses any address but loopback). IPAddressAllow takes addresses and networks, not host names, so the hosts modules are approved to call have to be listed by address. --modulePath, --moduleDataPath and --authConfigPath point into the three ReadWritePaths: their defaults ($HOME/countinghouse_modules, $HOME/.countinghouse/module_data, ./auth.json) are read-only under ProtectSystem=strict; modules write their /data and /tmp under --moduleDataPath, and the file auth provider writes auth.json with a demo key on first run. All three directories must exist and belong to the service user. PrivateTmp=yes does not affect modules’ /tmp, which lives under --moduleDataPath.

Honest comparison

Approach Isolation strength Density / cold start Operational cost
worker_threads (current, with the module sandbox) Separate V8 heap + execution context; in-process lockdown, permissions, a brokered per-module file namespace and limits on top; shared OS process, and shared network until parts 3-4 Very high density (threads, not processes); near-zero cold start Minimal — no extra infra
Linux containers (Docker/OCI, no extra sandboxing) Separate filesystem/network namespace, cgroup resource limits; shared host kernel High density; cold start ~100ms–1s Moderate — container orchestration
gVisor (or similar user-space kernel) Syscalls intercepted/emulated by a sandboxed kernel; strong defense against kernel-exploit-based escape Medium density; cold start adds tens of ms over a bare container Moderate-high — gVisor runtime + monitoring
Micro-VMs (Firecracker, etc.) Full hardware-virtualized isolation; separate kernel per tenant Lower density than containers; cold start ~100ms+ (improving) High — VM-level infra, harder multi-tenant bin-packing
V8 isolates (Cloudflare Workers / workerd) Separate V8 isolate per tenant, similar boundary to worker_threads but combined with a locked-down, purpose-built runtime (no fs, no arbitrary native addons, curated globals) Extremely high density; sub-millisecond cold start Requires a custom, restricted runtime — not “just run npm packages”

worker_threads sits at the weak end of this table on isolation strength, and its main advantage — density and cold-start — is exactly the same advantage the V8-isolate row gets plus a far smaller attack surface, because workerd-style runtimes deliberately don’t expose fs, unrestricted native addons, or a real process global. countinghouse’s isolation model is closer to “same process, separate heap” than to any of the harder options in this table — it should not be described as comparable to gVisor or micro-VM isolation.

Positioning

“Worker-thread isolation + module review (structural verification, plus operator review)” fits a semi-trusted, operator-vetted third-party module model — modules are vetted by the platform operator (structural verification, and in practice, human review) before being loaded, not open to anonymous, unreviewed code execution. It does not provide hard isolation equivalent to containers, gVisor, or micro-VMs, and should not be marketed as such. The honest pitch is: this is a reasonable, low-overhead boundary for modules from developers the operator has a relationship with and has reviewed, not a boundary suitable for running arbitrary, adversarial, unreviewed code from the open internet. (countinghouse itself runs no marketplace — modules are distributed over npm — so “marketplace” described the trust posture, not a feature of this project; see docs/superpowers/specs/2026-09-04-marketplace-backend-design.md for why the framing changed.)

Roadmap

The module sandbox is delivered in four parts. Parts 1 (foundation) and 2 (file broker and virtual paths, 8.0.0) are what this document describes. The rest is not implemented:

Beyond the programme, as before: a hybrid mode with an opt-in process- or container-per-module mode for modules the operator wants stronger isolation for, at the cost of density and cold-start, or a container or microVM shell around the whole process. The sandbox does not replace either; it is the in-process layer that remains useful under both.