How Loom and Cortex operate together at runtime. Loom is the brain; Cortex is the muscle. Loom stores assets, owns pipeline definitions and drives processing runs; Cortex is a fleet of worker daemons that register with Loom and execute the individual tasks Loom hands them.
Architecture Overview
The platform is a set of separately deployed components. The dashed boxes below are deployment boundaries (containers / processes); solid boxes are the parts inside them. Loom and Cortex both read the shared media storage at the bottom.
Two planes connect Loom and Cortex — do not confuse them:
| Plane | Transport | Carries |
|---|---|---|
Control |
Processor WebSocket ( |
Registration, heartbeats, task dispatch (source/node/segment), task results, live tracking events. |
Data |
REST ( |
The durable result payloads written back into Loom, keyed by asset. |
Cortex always dials out to Loom on port 8092; Loom never connects to Cortex.
How Loom Dispatches Work
Loom owns the pipeline graph and dispatches a task per asset to the Cortex fleet. Cortex A runs the source node, scans the shared filesystem and reports the discovered assets to Loom (Loom reads). Loom then dispatches processing tasks to Cortex B and C, which read their file and process it in parallel — each node colouring in at its own speed. Results return asynchronously: the faster worker (B) finishes and returns first, C follows later (Loom writes). The pipeline strip mirrors the active nodes.
Worker Lifecycle
A Cortex worker connects to Loom and serves the tasks Loom dispatches:
-
Registers — opens the processor WebSocket, authenticates (
?token=<jwt>), and announces the node kinds it is willing to run. Loom persists it as a durablecortex_instance. -
Waits for work — Loom’s pipeline engine dispatches a source task to enumerate media, then a node task per graph node per item — or per element, where an upstream node emitted a sequence (affinity work goes out as segment tasks).
-
Runs one task at a time — the task carries the node’s inputs keyed by its own input ports, resolved by Loom from the graph’s edges; the worker executes the node and replies with the outcome (
COMPLETED/FAILED/SKIPPED) plus its outputs, keyed by output port. -
Persists results — the worker writes the durable payload to Loom over REST (see persistence path).
-
Streams progress — tracking events flow back over the WebSocket; Loom re-broadcasts them to UI clients on
/api/v1/pipelines/events/ws.
Loom, not the worker, decides what runs next. Every dispatched task gets exactly one result — a node
that throws is reported FAILED, never dropped.
Connecting Cortex to Loom
LOOM_HOST=loom.internal LOOM_PORT=8092 LOOM_TOKEN=<jwt> \
docker run --rm -e LOOM_HOST -e LOOM_PORT -e LOOM_TOKEN metaloom/cortex-server:latestSee Cortex Configuration and Cortex Containers.
Deployment Overview
The same architecture at container level — what actually runs as an image, what scales, and what is created on demand. Solid-bordered boxes are long-lived containers, the teal dashed box is provisioned per chat and reaped again, and the purple boxes want a GPU.
Everything except the GPU model services ships as a MetaLoom image — see
Container Images for the image names and the full port table. The Cortex pools are
the same image with a different node whitelist; splitting them is what keeps a whisper task from
occupying a machine that should be hashing.
Deployment Patterns
| Pattern | Description |
|---|---|
Worker Deployment |
One or more Cortex replicas run as a long-lived |
Specialised pool |
A separate Cortex Deployment advertises only heavy kinds (e.g. |
Side-car |
Cortex runs next to Loom in the same compose stack for small setups. |