@nexus/engine

The shape of it

A pure function over a graph.

No magic. The engine takes a graph definition, a set of input events, and a few injected interfaces (state store, event bus, secret resolver, MCP client). It returns a stream of execution events.

import { runWorkflow } from "@nexus/engine";
import { graph } from "./onboarding.workflow.json";

const events = runWorkflow(graph, {
  trigger: { kind: "webhook", payload: { email: "a@example.com" } },
  state:    postgresStore(pool),     // or in-memory, or your own
  bus:      sqsBus(queueUrl),        // or memory bus, or kafka, etc.
  mcp:      mcpClient({ servers }),
  secrets:  awsSecretsManager(),
});

for await (const e of events) {
  // e is a StepStarted | StepCompleted | StepFailed | RunDone
  console.log(e);
}

Properties

Three properties that matter.

01 — Pure

No global state.

Everything the engine touches is passed in: stores, buses, clocks, secrets. You can run two workflows in the same process, on different stores, with different MCP server pools. No singletons.

02 — Deterministic

Same inputs → same trace.

The engine records every input to every node. Replays use the recorded inputs by default — even LLM calls, unless you opt back into live calls. Bug repros are exact.

03 — Portable

Zero cloud lock-in.

The reference adapters target Postgres, Redis, SQS, Bedrock — but every adapter is an interface. Bring your own queue, your own store, your own LLM. The engine doesn't care.

Where teams use it

Three shapes we see most often.

Local dev

The CLI runs the same engine.

nexus run ./graph.json spins up the engine in your terminal with an in-memory bus and store. Inspect every step in the same execution event format the cloud emits.

CI checks

Workflow tests, like unit tests.

Import the engine in your test runner. Stub MCP responses. Assert on emitted events. Keep workflow correctness in your existing test pipeline.

Embedded

Run inside your own host.

Got a service that already has a queue and a database? Embed the engine in your worker. You get the executor, observability, and replay — without adopting our hosting story.

Edge / private

On-prem or VPC-only.

The engine has no outbound network needs by default. Pair it with a private MCP fleet and a private LLM (Bedrock-VPC or a self-hosted model) — the whole stack stays inside your network.

Try it

npm install @nexus/engine

Or read the architecture deep-dive to see how the engine talks to the rest of the platform.

Engine docs → Architecture →

The same engine, anywhere TypeScript runs.