Getting Started

The mental model in one breath: a node is a Docker container that reads JSON on stdin and writes JSON out, a link is an arrow that passes one node's output to the next node's input, and a workflow is the graph (workflow.json) wiring them together. That is the whole model - everything below is just creating nodes, linking them, and running the graph. The full reference is in Workflows.

Requirements

• Node.js >= 20 (download)
• Docker with daemon running (download)

Install

Install both the orchestrator and the execution server:

npm install -g light-process @enixcode/light-run

Installed globally, light is a command everywhere. Prefer a project-local install? Drop the -g and prefix commands with npx - the binaries land in node_modules/.bin, which is not on your PATH, so plain light will not be found:

npm install light-process @enixcode/light-run
npx light doctor
npx light run example

light-process delegates container execution to light-run. Two usage modes:

• All-in-one (default): leave LIGHT_RUN_URL unset. light serve and light run auto-spawn a local light-run process on a free port (requires the binary above).
• Explicit runner: start light-run serve yourself, then point LIGHT_RUN_URL at it. Useful when the runner lives on a separate host or you want to share it across terminals.

Verify your environment:

light doctor

Expected output when LIGHT_RUN_URL is unset (all-in-one mode):

Checking environment...

  [ok] Node.js: v20.x.x
  [warn] LIGHT_RUN_URL: not set (all-in-one mode)
  [ok] light-run binary: found - `light serve` will start it automatically

[ok] Ready (all-in-one)

When LIGHT_RUN_URL is set and the runner is reachable:

Checking environment...

  [ok] Node.js: v20.x.x
  [ok] LIGHT_RUN_URL: http://localhost:3001
  [ok] light-run /health: reachable

[ok] Ready

Create a project

light init my-project
cd my-project

This creates:

my-project/
  package.json
  main.js                           # SDK usage example
  example/
    workflow.json                    # DAG definition
    hello/
      .node.json                     # node config
      index.js                       # code
      lp.js                          # helper
      lp.d.ts                        # types (autocomplete)

Run the example

light run example

Running: Example (from folder)
> Hello
  [Hello] Input: {}
  [ok] Hello 2100ms

-> {"hello":"world","input":{}}

[ok] 2108ms

Run with input

light run example --input '{"name": "Alice"}'

-> {"hello":"world","input":{"name":"Alice"}}

Run from code (main.js)

light init also dropped a main.js. It does exactly what light run example does, but from JavaScript via the SDK instead of the CLI - this is how you embed light-process inside a real app:

import { LightRunClient, loadWorkflowFromFolder } from 'light-process';

const wf = loadWorkflowFromFolder('./example');
const result = await wf.execute({}, { runner: new LightRunClient() });

console.log(result.success ? 'Success' : 'Failed');
console.log(JSON.stringify(result.results, null, 2));

node main.js

The CLI is for iterating; the SDK is for integrating (build graphs in code, hook onNodeStart/onLog callbacks, expose workflows over HTTP). See the SDK Guide for the full surface.

Validate a workflow

light check example

Checking: Example (from folder)

  [ok] workflow.json exists
  [ok] workflow.json structure
  [ok] Workflow loads
  [ok] Nodes valid - 1 node(s)
  [ok] Links valid - 0 link(s)
  [ok] Entry nodes - 1 entry node(s)

[ok] 6/6 checks passed

Visualize the DAG

light describe example

Outputs a text tree and generates describe.html with an interactive Mermaid diagram.

Start the server

light serve --port 3000

This starts the REST API server. The web dashboard (ui/out/) is not built by default - if it is absent, GET / returns 404 and a warning is printed at startup. To build the UI:

cd ui && npm install && npm run build

Once built, open http://localhost:3000 to see the web dashboard.

Add a new node

cd example
light init --node ./transform

This creates a transform/ folder with .node.json, index.js, lp.js, and auto-registers it in workflow.json.

Wire it to the existing hello node so output flows from one to the other:

cd ..
light link example --from hello --to transform

Verify the links were added:

light link example --list

Use --when to add a condition (link fires only when the condition matches):

light link example --from hello --to transform --when '{"status": "ok"}'

Add a Python node

light init --node ./analyze --lang python

Creates analyze/ with .node.json, main.py, lp.js, lp.py, and input.json using python:3.12-alpine.

Next steps

• CLI Reference - all commands and flags
• SDK Guide - build workflows in code
• Workflows - folder structure and linking
• Conditions - conditional routing