Isolates
An Isolate runs a module you don't control: a customer's pricing rule, a third-party plugin, code a model generated. It has its own V8 heap and shares a small pool of threads with every other isolate, so a process can hold thousands of them.
An isolate computes, and nothing else. It holds no capability and can be granted none: no files, no network, no environment. It reaches the outside only through the host functions you hand it.
import { Isolate } from "runtime:workers";
const rule = new Isolate({
source: "export const discount = (order) => (order.total > 500 ? 0.1 : 0);",
name: "acme-discount",
});
const { discount } = await rule.exports;
console.log(await discount({ total: 600 })); // 0.1
rule.terminate();esrun --allow-workers main.jsWhen to use one
| You need | Use |
|---|---|
| Many small pieces of someone else's code, each kept apart | Isolate |
| Heavy work spread across every core, or code that blocks | Worker |
| State that outlives the process, one owner per id | Durable workers |
Starting one
From a string, such as code kept in a database:
new Isolate({ source: code, name: "rule-42" });From a file:
new Isolate(new URL("./plugins/upper.js", import.meta.url));Starting an isolate needs --allow-workers. Starting one from a file also reads that file, so it needs --allow-imports too, as a Worker does. The file's static imports load with it. A module made from a string has no directory, so it can import only runtime: modules.
Calling it
isolate.exports resolves, once the module has evaluated, to its exported functions. Each call is async. Its arguments and its result are copied by structured clone, as postMessage copies a message.
const { transform } = await plugin.exports;
const html = await transform(markdown);An error thrown inside keeps its class, message and code:
try {
await validate(input);
} catch (e) {
if (e instanceof RangeError && e.code === "ERR_LIMIT") retryLater();
}A result that can't be cloned, such as a function, rejects with a DataCloneError.
Handing it what it needs: host
host is how an isolate reaches the outside. Each function you pass runs in your program, with your program's permissions, and the isolate calls it by name:
// main.js
const plugin = new Isolate(new URL("./plugin.js", import.meta.url), {
host: {
log: (...args) => console.log("[plugin]", ...args),
config: async (key) => settings[key],
},
});
// plugin.js
import { host } from "runtime:workers";
export async function transform(text) {
await host.log("transforming", text.length);
return (await host.config("shout")) ? text.toUpperCase() : text;
}A function in host can do whatever your program can. Hand over narrow ones: getUser(id) that fetches one record from one API, not fetch(url). A host function that takes a path and reads it gives the isolate your read permission by another route.
What runs inside
| Works | Refused |
|---|---|
Web standards: URL, TextEncoder, structuredClone, crypto, timers, console | runtime:fs, fetch, runtime:net, runtime:db, runtime:http, env |
runtime: modules that need no permission: path, serialization, hashing, pdf, images, archive on bytes passed in | import() of a file, starting a Worker or an Isolate, Atomics.wait |
A refused call fails like any denied capability, with ERR_CAPABILITY_DENIED, and the message says what to do instead:
capability denied: FileRead (permission "read") — an isolate is computation
only; pass it what it needs through a host functionInside an isolate, runtime:workers exports only host.
Messages
postMessage and onmessage work as they do on a Worker, for one-way events:
const iso = new Isolate({ source: "onmessage = (e) => postMessage(e.data * 2);" });
iso.onmessage = (e) => console.log(e.data); // 42
iso.postMessage(21);Memory and CPU
memory caps the isolate's heap, in megabytes, at no more than your program's own (and at least 8 MB, the least an isolate starts in), and caps its ArrayBuffer storage at the same size — buffers live outside the heap, so a heap limit alone would not hold them. Buffers that are garbage don't count once they are collected; until then, an isolate may briefly hold up to twice its memory in buffers. cpuTime caps how much CPU time, in milliseconds, one turn may use — one stretch of the isolate's code, from when it gets its thread until it next waits:
new Isolate(code, { memory: 32, cpuTime: 50 });A loop that never ends, for (;;) await null included, is one turn, so it is stopped soon after its budget. Waiting is not in a turn: an isolate waiting on a host function or a timer uses none of it. Work that awaits between short pieces is never stopped, and never holds its thread either.
Past either limit the isolate is terminated. Its waiting calls reject with ERR_ISOLATE_CPU_LIMIT or ERR_ISOLATE_MEMORY_LIMIT, and later calls with ERR_ISOLATE_TERMINATED.
try {
await rule.evaluate(order);
} catch (e) {
if (e.code === "ERR_ISOLATE_CPU_LIMIT") disableRule(tenant);
}Starting fast
An isolate takes a little under a millisecond to start. When a request is waiting on one, build some ahead of time:
await Isolate.prepare(32); // 32 isolates built and waiting
// Later: each of these claims one, and starts in tens of microseconds.
const rule = new Isolate({ source: code });A prepared isolate is claimed only by an isolate without its own memory, since a memory ceiling is fixed when an isolate is made. Unclaimed ones don't keep the process running.
Ending
terminate() stops an isolate at once, even one stuck in a loop. Calls still waiting reject with ERR_ISOLATE_TERMINATED, and so does any later call.
A module that throws while it loads rejects exports and fires error:
iso.onerror = (e) => {
e.preventDefault(); // handled here, so it is not logged
report(e.error);
};A live isolate keeps the process running, as a Worker does. Call terminate() when you are done with it, or unref() to let the process exit while it idles.
Limits
An isolate is not a hard security boundary. It keeps code apart from your program's data and permissions, not from attacks on the CPU itself.
Isolates on one pool thread take turns. Without
cpuTime, a call that loops forever holds up the others on its thread until youterminate()it. Give isolates running code you don't control acpuTime.From inside an isolate,
cwd()is refused, soresolve()of a relative path is too.join()and the rest ofruntime:pathwork.
See the runtime:workers reference for every option, and Internals: Workers for how the pool works.