Skip to main content
ModuleX feels live in two different ways. When you run a workflow, you watch each step report its progress in real time. When you build a workflow with a teammate, you see their cursor move and their edits appear on the same canvas as yours. These are two separate systems, and keeping them apart is the whole mental model. This page gives you that model in plain terms: what each realtime system does, when each one is in play, and what to expect when several people work together. For the wire-level detail, follow the links into Realtime overview & event taxonomy.

​
Two realtime planes

Think of ModuleX as having two independent “live” channels that never overlap. One pushes a run’s progress to you. The other keeps everyone’s canvas in agreement.

Run streaming (SSE)

A one-way feed of a run’s progress: the workflow, the AI Composer, or the Assistant reports each step to you as it happens.

Canvas collaboration (Socket.io)

A two-way sync of the workflow canvas: cursors, presence, locks, and edits flow between everyone in the same workflow.
“Realtime” in ModuleX always means one of these two systems. They share no events and no connection. A run streaming to you over SSE is unrelated to your teammate editing the canvas over Socket.io — even when both are happening in the same workflow at the same time.

​
Run streaming: watching a run as it happens

When you start a run, ModuleX opens a live feed of that run’s progress over Server-Sent Events (SSE). It is a one-way stream: the server sends you events as the run moves forward, and you watch. You see this feed in three places, and they all work the same way:

Workflow runs

Each node reports when it starts, when it finishes, and what it produced — until the run reaches done.

AI Composer

The Composer streams its thinking and the changes it makes to your canvas as it builds.

Assistant

The Assistant streams its response and the tool calls it makes, step by step.
A run’s stream carries a small set of progress events. You do not need to memorize them, but it helps to recognize the rhythm:
1

The run starts

The first event describes the run: which workflow, which version, and the run’s identifier.
2

Each step reports in

As the run progresses, you get an event when a node (or an Assistant tool call) starts, and another when it produces output. If a step fails, you see the failure and any automatic retry.
3

The run finishes

The stream ends with a final event — done when the run completes, or error if it could not. A run you cancel ends with cancelled instead.
The stream is one-way. To act on a run — to cancel it, or to answer a question it asks — you make a separate request; you do not “reply” on the stream. See SSE run streaming for the full event list and frame format, and Human-in-the-loop (HITL) resume for how a paused run is answered.

​
When a run pauses to ask you something

Some runs stop and wait for a person. A workflow can include an interrupt step, and the AI Composer and Assistant can pause to ask for a choice, a confirmation, or a credential before continuing. This is human-in-the-loop (HITL). When this happens, the stream goes quiet — it does not end. The run is waiting. You answer the question (in the app, or with a separate request via an SDK), and the run continues. Because answering restarts the run’s progress, you reconnect to a fresh stream to watch the rest.
A paused run holds its place for a while, then expires if no one answers. The exact pause-and-resume mechanics — what kinds of questions a run can ask, and how each is answered — are covered in Human-in-the-loop (HITL) resume.

​
Canvas collaboration: building together live

The second realtime system is for the workflow builder. When two or more people open the same workflow, ModuleX connects them over Socket.io so the canvas stays in sync. Unlike run streaming, this is a two-way conversation: every person both sends their changes and receives everyone else’s.

Presence

You see who else is in the workflow, each with their own color, and their live cursor as they move around the canvas.

Locks

When someone is editing a node, it is locked to them so two people cannot overwrite the same node at once.

Live edits

Adding, moving, connecting, or deleting nodes is broadcast to everyone in the workflow as it happens.

Versioning

Each accepted edit advances a version so the server can keep everyone consistent and resolve conflicts.

​
Who can edit

Collaboration follows the same roles as the rest of ModuleX. Anyone in the organization can open a workflow and watch, but editing the canvas requires an owner or admin.
There is no member role in ModuleX. A member role existed in earlier versions and was retired on 2026-06-20. The live roles are owner and admin only, and editing the canvas — adding, moving, connecting, or locking nodes — is restricted to those roles. See Roles & permissions for the full map.

​
Conflicts are handled for you

When several people edit quickly, two changes can arrive based on slightly different versions of the canvas. ModuleX detects this and asks the affected client to rebase onto the latest version, rather than letting one person silently overwrite another. You do not manage this by hand; the builder keeps everyone converged. The version, lock, and conflict details are in Presence, locks & versioning.

​
External sync: when a workflow changes outside the canvas

Not every change to a workflow comes from a person dragging nodes. The AI Composer edits the workflow on your behalf, and a workflow can also be changed through the API. ModuleX needs everyone with the canvas open to see those changes too. This is external sync. When a workflow is edited from outside the live canvas, that change is delivered to everyone currently viewing the workflow over the same Socket.io collaboration system, using the workflow:external-sync event. The canvas updates in place, just as it would for a teammate’s edit.
External sync runs over the live Socket.io workflow:external-sync event — that is the path that keeps the canvas in sync. The event reference is Socket.io collaboration events.

​
Putting it together

The two systems often run at once, and that is fine — they do not interfere.
You and a teammate are both in the same workflow. Your teammate adds a node; you see it appear over canvas collaboration. Meanwhile you run the workflow; you watch its steps complete over run streaming. Two live systems, two purposes, no conflict.
You ask the AI Composer to restructure the workflow. The Composer streams its progress to you over run streaming, and the edits it makes land on everyone else’s canvas over external sync on the collaboration system.
A run reaches a human-in-the-loop step. Its run stream goes quiet while it waits. You answer, and a fresh stream picks up where it left off. The canvas, and anyone editing it, is unaffected.

​
Where to go next

Realtime overview & event taxonomy

The technical map of both planes — every SSE event and every Socket.io event in one place.

Realtime collaboration walkthrough

Invite a teammate and co-edit a workflow live, step by step.

Canvas collaboration

What co-editing looks like in the app: presence, cursors, and live edits.

Realtime co-editing & external sync

How canvas edits and external changes sync, in the builder’s own terms.