Agents, agent clusters & realms

Three words that sound alike

This lesson is about three words. They sound alike, but each one answers a different question:

• An agent is the thing that runs your JavaScript. It answers: who runs this code?
• An agent cluster is a group of agents. It answers: which agents may share some things?
• A realm is one set of global things: one globalThis and one copy of the built-ins, like Array. It answers: which Array does this code use?

This lesson comes after Modules through a bundler. The next lesson, How workers work, shows what it costs to start a new agent and to send data to it.

What an agent is

An agent is the thing that runs JavaScript. It runs one job at a time. Each agent has its own:

• call stack: the functions running right now,
• job queue: the work waiting to start,
• realms: its sets of global things.

The page in a browser tab is one agent. Each worker is another agent. A worker is a script that runs beside the page, on its own.

console.log(typeof globalThis, typeof Array);

Line 1 uses typeof. It gives a word that says what kind of value a name holds. The line prints object function:

• globalThis is an object.
• Array is a function that makes arrays.

This only tells you about the agent that runs the line. A worker has its own globalThis, so this line says nothing about it.

Two agents can run at the same time when the computer gives each one its own thread. A thread is a separate line of work that the computer runs alongside others. Even so, the main rule is simple: normal code in a worker does not share globalThis with the page.

Agent clusters and shared memory

An agent cluster is a group of agents that may share some things. A page and the workers it starts can be in one cluster.

Most values you send to a worker are copied. The browser makes a fresh copy with a method called structured clone. The worker gets the copy, not your original.

A SharedArrayBuffer is different. It is a block of raw bytes that several agents can use together, when the browser allows it. If one agent changes a byte, the others see the change.

const bytes = new SharedArrayBuffer(4);
const pageView = new Int32Array(bytes);
const workerView = new Int32Array(bytes);
pageView[0] = 3;
console.log(workerView[0]);

The code reads the bytes through a typed array. A typed array, like Int32Array, is a view that reads bytes as numbers. Line by line:

• Line 1 makes 4 shared bytes.
• Lines 2 and 3 make two views of those same bytes.
• Line 4 writes 3 through pageView.
• Line 5 reads through workerView and prints 3.

This code has no Run button. The lesson editor can't turn on the safety settings that SharedArrayBuffer needs.

Browsers usually let a page use SharedArrayBuffer only when the page is cross-origin isolated. That means the page sends two safety headers. They keep content from other websites out of the page unless that content agrees.

Sharing bytes does not make teamwork safe on its own. When two agents read and write the same bytes, they use Atomics. Atomics is a set of functions that do each read or write as one whole step, so the agents agree.

1const pageAgent = { cluster: "school", memory: new Int32Array(1) };Run2const workerAgent = { cluster: "school", memory: pageAgent.memory };3 4pageAgent.memory[0] = 3;5console.log(workerAgent.memory[0]);

Realms and their built-ins

A realm is one set of global things. It has its own globalThis and its own built-ins, the intrinsics.

An iframe is a common example. An iframe is a small page shown inside another page. It has its own:

• globalThis,
• Array,
• Object.prototype, the object where all plain objects find shared methods,
• Promise.

const frame = document.createElement("iframe");
document.body.append(frame);

const frameArray = new frame.contentWindow.Array("tea");
console.log(frameArray instanceof Array);
console.log(Array.isArray(frameArray));
console.log(frame.contentWindow.Array === Array);

Every array is linked to an object called Array.prototype. That is where shared methods, like push, live. Line by line:

• Lines 1 and 2 make an iframe and add it to the page.
• Line 4 makes an array with the iframe's own Array.
• Line 5 prints false. The array is linked to the iframe's Array.prototype, not to the page's.
• Line 6 prints true. Array.isArray sees that the value is an array.
• Line 7 prints false. The iframe's Array and the page's Array are two different functions.

This code has no Run button. Try it in a normal page, with an iframe from the same website. The lesson editor runs code in a locked-down frame, so it can't read the iframe's contentWindow, which is the iframe's own globalThis.

A realm is not a thread. One agent can have several realms. So a new iframe gives you a new Array, but the iframe's code does not run at the same time as the page.

Checking a value from another realm

value instanceof Array asks a yes-or-no question: is this value linked to this realm's Array.prototype? It follows the value's chain of linked prototypes to find out.

Inside one realm, that works. But an array from an iframe is linked to the iframe's Array.prototype, so the page's check says no. That makes instanceof a weak check for values that come from an iframe or a worker.

1const pageArray = { realm: "page", values: ["tea"] };Run2const frameArray = { realm: "frame", values: ["tea"] };3 4function check(value) {5  return {6    instanceofArray: value.realm === "page",7    isArray: Array.isArray(value.values),8  };9}10 11console.log(check(frameArray).instanceofArray, check(frameArray).isArray);

The replay uses a small model, not a real iframe. The model marks one array as made in the frame, so its instanceof Array result is false. Array.isArray still says true. A real iframe array gives the same two answers.

The table lists checks that look alike. Read each row as: "when I write this check, it depends on this, and here is a safer choice."

One symbol list for the whole cluster

Each realm has its own built-ins. But a few things are shared by the whole cluster. One of them is the global symbol registry.

• A symbol is a unique value. It is often used as a property key.
• The global symbol registry is a list of symbols. Each symbol is saved under a name.
• Symbol.for("cart") looks up the name cart in that list. If the name is not there yet, it adds a new symbol.
• Plain Symbol() always makes a brand-new symbol. It never uses the list.

const frame = document.createElement("iframe");
document.body.append(frame);

const pageKey = Symbol.for("cart");
const frameKey = frame.contentWindow.Symbol.for("cart");
console.log(pageKey === frameKey);

• Lines 1 and 2 make an iframe and add it to the page.
• Line 4 asks the list for cart from the page.
• Line 5 asks the list for cart from the iframe.
• Line 6 prints true. The page and the iframe are in the same cluster, so they share one list and get the same symbol.

This is one shared list. It does not mean every object is shared.

This code has no Run button. Try it in a normal page, with an iframe from the same website. The lesson editor's locked-down frame can't read the iframe's contentWindow.

Don't use this list to send data between realms. Send data on purpose, for example in a message. Use Symbol.for only when you need the same symbol in each realm.

The ShadowRealm proposal

ShadowRealm is a proposed new feature. TC39, the group that decides what goes into JavaScript, is still working on it. It would let your code make a fresh realm inside the current agent:

• The new realm would have its own globalThis and its own built-ins.
• It would not get a new thread.

if (typeof ShadowRealm === "function") {
  const realm = new ShadowRealm();
  console.log("available");
} else {
  console.log("not available");
}

Line 1 checks that ShadowRealm exists before line 2 uses it. This is called feature detection: you test for a feature before you use it. If the check fails, line 5 prints not available.

In September 2026, the proposal's page says Stage 2.7. A stage shows how far a proposal has got. It does not mean browsers have the feature. So this lesson never says it is available, and the example checks first.

ShadowRealm's goal is to keep one set of globals and built-ins apart from another, inside the same agent. It does not replace workers or the browser's rules about other websites. It is not a safe place to run code you don't trust.

Try it: one array, two realms

Change one thing at a time:

1. Pick the realm that makes an array.
2. Pick the realm that checks it.
3. Choose whether the two agents are in one cluster. Only agents in one cluster may share memory.

const sameRealm = madeIn === checkedIn;
console.log(sameRealm);       // like instanceof Array
console.log(true);            // like Array.isArray
console.log(true);            // like comparing two Symbol.for("cart")
console.log(sameCluster);     // may the agents share memory?

When the two realms are different, instanceof Array is false, but Array.isArray stays true. The Symbol.for result stays true, because the realms share one symbol list. When you untick the cluster box, shared memory is no longer allowed.

Where you meet this in real code

Most apps meet agents and realms in one of these places:

• an iframe on your page,
• a worker,
• a test tool that runs code in a fresh realm (Node calls this a VM context),
• a library that gets values from other code.

The safe habit is the same in each place. Send plain data, like strings, numbers, arrays, and plain objects. Write down the shape each message should have. Structured clone copies plain data well, and the copy doesn't depend on the sender's prototypes.

import vm from "node:vm";

const list = vm.runInNewContext("[]");
console.log(list instanceof Array);
console.log(Array.isArray(list));
console.log(vm.runInNewContext("Symbol.for('cart')") === Symbol.for("cart"));

This code runs in Node, not in the browser. vm.runInNewContext runs a piece of code in a fresh realm and hands back the result. Line by line:

• Line 3 makes an empty array in the new realm.
• Line 4 prints false. The array is linked to the new realm's Array.prototype.
• Line 5 prints true. Array.isArray still sees an array.
• Line 6 prints true. Both realms get the same symbol for cart, because they share one symbol list.

import { Worker, isMainThread, parentPort } from "node:worker_threads";

if (isMainThread) {
  globalThis.schoolName = "Page school";
  new Worker(new URL(import.meta.url)).once("message", console.log);
} else {
  parentPort.postMessage(globalThis.schoolName === undefined);
}

This Node file runs twice: once as the main program, and once as a worker. isMainThread is true only in the main program.

• Line 4: the main program sets globalThis.schoolName.
• Line 5: it starts a worker from the same file. It prints the first message the worker sends.
• Line 7: the worker checks whether schoolName is undefined in its own globalThis, and sends the answer.

The program prints true. The worker is a separate agent with its own globalThis, as in the picture of the page and the worker.

Common mistakes

• “A realm is a thread.” A realm is one set of global things. A worker is an agent, and it has its own realm.
• “Agents in a cluster share every value.” Normal messages are copied. Only special tools, like SharedArrayBuffer, share bytes.
• “instanceof works the same for every value.” It looks for one realm's prototype, so it can say no to a real array from another realm.
• “Every browser has ShadowRealm.” It is still a proposal, at Stage 2.7. Check that it exists before you use it.

Practice exercises

console.log(typeof globalThis, typeof Array);

Check your understanding

Keep the three words apart. Agents run code. Clusters decide what agents may share. Realms hold the globals and built-ins.

Key takeaways

• An agent has a call stack, a job queue, and realms. The page and each worker are separate agents.
• An agent cluster decides what agents may share, such as a SharedArrayBuffer.
• Each realm has its own globalThis and its own built-ins, like Array.
• To check for an array from another realm, use Array.isArray, not instanceof Array.
• ShadowRealm is a Stage 2.7 proposal. Check that it exists before you use it.

Coming next: How workers work.