Light Process

$ npm install -g light-process

$ light doctor

Checking environment...

  [ok] Node.js: v20.x.x
  [ok] Docker: Docker version 24.x.x
  [ok] Docker daemon: running

[ok] Ready

$ light init my-project
$ cd my-project

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

$ light run example

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

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

[ok] 2108ms

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

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

$ 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

$ light describe example

$ light serve --port 3000

$ cd example
$ light init --node ./transform

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

$ light run <file|dir|id|name> [options]
$ light run --node [dir] [options]

# Run from folder
$ light run my-workflow

# Run with inline JSON input
$ light run my-workflow --input '{"key": "value"}'

# Run with input file
$ light run my-workflow --input data.json

# Full JSON output (for piping)
$ light run my-workflow --json | jq '.results'

# Run a single node
$ light run --node ./my-node

# Single node with input.json auto-loaded
$ cd my-node && light run --node .

# Search by name in a directory
$ light run my-workflow --dir ./custom-workflows

$ light serve [dir] [--port 3000] [--verbose]

# Serve all workflows in a directory
$ light serve

# Custom port
$ light serve --port 8080

# Verbose Docker logging
$ light serve --verbose

# Set a custom API key
$ LP_API_KEY=my-secret-key light serve

# Public - no auth needed
$ curl http://localhost:3000/health

# Protected - requires Bearer token
$ curl -H "Authorization: Bearer <your-api-key>" http://localhost:3000/api/workflows

$ light init [dir]                    # full project
$ light init --node [dir] [--lang]    # single node

$ light check <file|dir> [--fix]

$ light describe <file|dir|id|name> [--no-html]

  Order Pipeline (order-pipeline)
  3 nodes, 2 links

  Validate (node:20-alpine)
    in: name (string), age (integer)
    out: valid (boolean), score (number)
    -> Process [valid = true]
  Process (python:3.12-alpine)
    out: result (string)
    -> Notify
  Notify (node:20-alpine)

$ light doctor

$ light config <get|set|list|path> [key] [value]

$ light remote <bind|set-key|use|forget|ping|ls|run|delete|rm> [...]

$ light pull <id> [--path <dir>] [--force] [--remote <name>]
$ light pull --all [--force]

$ light push [<name>] [--path <dir>] [--remote <name>] [--yes]

$ light link <workflow-dir> [--from <id> --to <id>] [--when <json>]
$ light link <workflow-dir> --edit <link-id> [--when <json>] [--data <json>]
$ light link <workflow-dir> --list
$ light link <workflow-dir> --remove <link-id>

$ light list [--dir <path>] [--json]

$ light pack [<folder>] [--to <file>] [--force] [--keep]

$ light unpack <file> [--to <dir>] [--force] [--keep]

$ light node info <dir> [--json]
$ light node schema <dir>
$ light node register <dir>
$ light node helpers <dir>

# Show node info and what it receives
$ light node info ./my-node
$ light node info ./my-node --json

# Edit the schema of an existing node folder
$ light node schema ./my-node

# Edit the hello example
$ light node schema ./example/hello

# Regenerate lp.d.ts after editing .node.json by hand
$ light node helpers ./my-node

$ npm install light-process

import { Workflow, DockerRunner } from 'light-process';

const wf = new Workflow({ name: 'hello' });

const node = wf.addNode({ name: 'Greet', image: 'node:20-alpine' });
node.setCode((input) => ({ message: `Hello, ${input.name}!` }));

const result = await wf.execute(
  { name: 'World' },
  { runner: new DockerRunner() }
);

console.log(result.success); // true
console.log(result.results);

import { Workflow, Schema, DockerRunner } from 'light-process';

const wf = new Workflow({ name: 'pipeline' });

// Node 1: validate
const validate = wf.addNode({ name: 'Validate', image: 'node:20-alpine' });
validate.inputs = Schema.object({ email: Schema.string() }, ['email']);
validate.setCode((input) => ({
  valid: input.email.includes('@'),
  email: input.email,
}));

// Node 2: process (only runs if valid)
const process = wf.addNode({ name: 'Process', image: 'node:20-alpine' });
process.setCode((input) => ({
  processed: true,
  email: input.email,
}));

// Node 3: reject (only runs if invalid)
const reject = wf.addNode({ name: 'Reject', image: 'node:20-alpine' });
reject.setCode((input) => ({
  rejected: true,
  reason: 'Invalid email',
}));

// Conditional links
wf.addLink({
  from: validate.id,
  to: process.id,
  when: { valid: true },
});

wf.addLink({
  from: validate.id,
  to: reject.id,
  when: { valid: { ne: true } },
});

const result = await wf.execute(
  { email: 'alice@example.com' },
  { runner: new DockerRunner() }
);

import { Node, loadDirectory, DEFAULT_IGNORE } from 'light-process';

const node = new Node({
  name: 'My Node',
  image: 'node:20-alpine',
  entrypoint: 'node index.js',
});

// Load all files from a directory
const files = loadDirectory('./my-node', { ignore: DEFAULT_IGNORE });
node.addFiles(files);

// Or use the shorthand
node.addFolder('./my-node', 'node index.js');

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

const wf = loadWorkflowFromFolder('./my-workflow');
if (!wf) {
  console.error('Invalid workflow folder');
  process.exit(1);
}

const result = await wf.execute({}, { runner: new DockerRunner() });

import { exportWorkflowToFolder } from 'light-process';

// After building a workflow programmatically
exportWorkflowToFolder(wf, './output/my-workflow');
// Creates workflow.json + node folders with .node.json and code files

const result = await wf.execute(input, {
  runner: new DockerRunner(),
  timeout: 30000, // 30s global timeout

  onNodeStart: (nodeId, nodeName) => {
    console.log(`Starting: ${nodeName}`);
  },

  onNodeComplete: (nodeId, nodeName, success, duration) => {
    console.log(`${nodeName}: ${success ? 'ok' : 'failed'} (${duration}ms)`);
  },

  onLog: (nodeId, nodeName, log) => {
    console.log(`[${nodeName}] ${log}`);
  },

  onStatusChange: (status) => {
    console.log(`Current: ${status.currentNodeName}`);
    console.log(`Done: ${status.completedNodes.length}`);
  },
});

const runner = new DockerRunner({
  memoryLimit: '512m',
  cpuLimit: '1.5',
  runtime: 'runsc',       // 'runc', 'runsc' (gVisor), 'kata'
  gpu: 'all',             // false, 'all', number, or device ID
  verbose: true,
  tempDir: '/tmp/lp',
});

node.setCode((input) => {
  // input is the parsed JSON from stdin
  const result = { doubled: input.value * 2 };
  return result; // written to .lp-output.json
});

node.addHelper('javascript'); // adds lp.js
node.addHelper('python');     // adds lp.py
node.addHelper();             // adds all helpers

// To JSON
const json = wf.toJSON();
const str = JSON.stringify(json, null, 2);

// From JSON
const restored = Workflow.fromJSON(json);

import {
  LightProcessError,
  LinkValidationError,
  CircularDependencyError,
  WorkflowTimeoutError,
} from 'light-process';

my-workflow/                     # folder format (working copy)
  workflow.json                  # DAG definition
  node-a/
    .node.json                   # node config
    index.js                     # code
    lp.js                        # helper
  node-b/
    .node.json
    main.py
    lp.py
my-workflow.json                 # JSON format (portable)

{
  "id": "my-workflow",
  "name": "My Workflow",
  "network": null,
  "nodes": [
    { "id": "node-a", "name": "Node A", "dir": "node-a" },
    { "id": "node-b", "name": "Node B", "dir": "node-b" }
  ],
  "links": [
    { "from": "node-a", "to": "node-b" }
  ]
}

{
  "id": "node-a",
  "name": "Node A",
  "image": "node:20-alpine",
  "entrypoint": "node index.js",
  "setup": ["npm install axios"],
  "timeout": 10000,
  "network": null,
  "inputs": null,
  "outputs": null
}

{
  "from": "node-a",
  "to": "node-b",
  "when": { "status": "ok" },
  "data": { "extra": "value" },
  "maxIterations": null
}

{
  "from": "process",
  "to": "validate",
  "when": { "retry": true },
  "maxIterations": 3
}

{ "status": "ok" }

{ "status": "ok", "count": { "gte": 10 } }

{
  "or": [
    { "status": "ok" },
    { "status": "warning" }
  ]
}

{ "token": { "exists": true } }
// Matches if the output has a "token" field

{ "error": { "exists": false } }
// Matches if the output does NOT have an "error" field

{ "role": { "in": ["admin", "moderator", "owner"] } }

{ "score": { "gte": 0, "lte": 100 } }

{ "status": { "ne": "error" } }

{
  "links": [
    {
      "from": "validate",
      "to": "process",
      "when": { "valid": true, "score": { "gte": 80 } }
    },
    {
      "from": "validate",
      "to": "reject",
      "when": { "valid": { "ne": true } }
    }
  ]
}

wf.addLink({
  from: validate.id,
  to: process.id,
  when: { valid: true, score: { gte: 80 } },
});

Link "my-link" has invalid 'when' condition: Unknown operator: foo

const runner = new DockerRunner({
  memoryLimit: '512m',     // --memory flag
  cpuLimit: '1.5',         // --cpus flag
  runtime: 'runsc',        // --runtime flag
  gpu: 'all',              // --gpus flag
  noNewPrivileges: true,   // --security-opt (default: true)
  verbose: false,          // log Docker commands
  tempDir: '/tmp/lp',      // custom temp directory
});

# Created automatically on first use:
$ docker network create --driver bridge \
  -o com.docker.network.bridge.enable_icc=false \
  lp-isolated

{ "network": "none" }

{ "network": "my-custom-network" }

const runner = new DockerRunner({ gpu: 'all' });

lp-hello-1712345678901-0

const controller = new AbortController();

// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);

const result = await wf.execute(input, {
  runner,
  signal: controller.signal,
});

# Start the server (no auth - public)
$ light serve --port 3000

# Enable Bearer auth by setting LP_API_KEY
$ LP_API_KEY=my-secret-key light serve --port 3000

$ curl http://localhost:3000/.well-known/agent-card.json

{
  "name": "Light Process",
  "description": "Workflow engine with Docker container isolation",
  "url": "http://localhost:3000",
  "protocolVersion": "0.2.1",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "stateTransitionHistory": true
  },
  "defaultInputModes": ["application/json"],
  "defaultOutputModes": ["application/json"],
  "skills": [
    {
      "id": "my-workflow",
      "name": "My Workflow",
      "description": "Workflow: My Workflow (3 nodes)",
      "tags": ["workflow"]
    }
  ]
}

$ curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "message": {
        "messageId": "msg-1",
        "role": "user",
        "parts": [{
          "kind": "data",
          "data": {
            "workflowId": "my-workflow",
            "name": "Alice"
          }
        }]
      }
    }
  }'

# List all workflows (auth required)
$ curl -H "Authorization: Bearer <your-api-key>" http://localhost:3000/api/workflows

# Get workflow detail (auth required)
$ curl -H "Authorization: Bearer <your-api-key>" http://localhost:3000/api/workflows/my-workflow-id

# Health check (no auth required)
$ curl http://localhost:3000/health

# Add a workflow dynamically (auth required)
$ curl -X POST -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"id":"my-wf","name":"My Workflow","nodes":[...],"links":[]}' \
  http://localhost:3000/api/workflows

# Remove a workflow (auth required)
$ curl -X DELETE -H "Authorization: Bearer <your-api-key>" \
  http://localhost:3000/api/workflows/my-wf

import { createA2AServer, Workflow, DockerRunner } from 'light-process';

const runner = new DockerRunner();
const app = createA2AServer({ port: 3000, runner });

// Register workflows
app.registerWorkflow(myWorkflow);

// Start listening
await app.listen();

// Later: stop
await app.close();

createA2AServer({
  port: 3000,              // listen port (default: 3000)
  host: '0.0.0.0',         // bind host (default: '0.0.0.0')
  runner: new DockerRunner(), // shared runner instance
  card: {
    name: 'My Agent',       // agent name
    description: 'Custom',  // agent description
    url: 'https://my.host', // public URL
  },
});

import { Schema } from 'light-process';

Schema.string()                  // { type: 'string' }
Schema.string({ minLength: 1 }) // { type: 'string', minLength: 1 }
Schema.number()                  // { type: 'number' }
Schema.number({ minimum: 0 })   // { type: 'number', minimum: 0 }
Schema.integer()                 // { type: 'integer' }
Schema.boolean()                 // { type: 'boolean' }
Schema.array(Schema.string())   // { type: 'array', items: { type: 'string' } }
Schema.object(props, required)   // { type: 'object', properties, required }

node.inputs = Schema.object({
  name: Schema.string({ minLength: 1 }),
  age: Schema.integer({ minimum: 0, maximum: 150 }),
  tags: Schema.array(Schema.string(), { minItems: 1 }),
  active: Schema.boolean(),
}, ['name', 'age']); // required fields

node.outputs = Schema.object({
  result: Schema.string(),
  score: Schema.number({ minimum: 0, maximum: 100 }),
});

{
  "inputs": {
    "type": "object",
    "properties": {
      "name": { "type": "string", "minLength": 1 },
      "age": { "type": "integer", "minimum": 0 }
    },
    "required": ["name", "age"]
  },
  "outputs": {
    "type": "object",
    "properties": {
      "result": { "type": "string" }
    }
  }
}

Input validation failed: input.name: must NOT have fewer than 1 characters
Output validation failed: output.score: must be >= 0

import { validate, validateInput, validateOutput } from 'light-process';

const schema = Schema.object({
  name: Schema.string({ minLength: 1 }),
}, ['name']);

const result = validateInput({ name: '' }, schema);
// { valid: false, errors: ['input.name: must NOT have fewer than 1 characters'] }

const result2 = validateInput({ name: 'Alice' }, schema);
// { valid: true, errors: [] }

MAJOR.MINOR.PATCH-PRERELEASE

0.1.0-alpha.0   First alpha - core features, may have bugs
0.1.0-alpha.2   Second alpha - bug fixes from alpha.1
0.1.0-beta.1    Feature-complete, testing phase
0.1.0-beta.2    Bug fixes from beta.1
0.1.0-rc.1      Release candidate - final testing
0.1.0            Stable release
0.1.1            Patch - bug fix
0.2.0            Minor - new features
1.0.0            First major - stable API commitment

0.1.0-alpha.0 < 0.1.0-alpha.2 < 0.1.0-beta.1 < 0.1.0-rc.1 < 0.1.0

# Install latest stable (skips pre-releases)
$ npm install light-process

# Install specific pre-release
$ npm install light-process@0.1.0-alpha.0

# Install latest including pre-releases
$ npm install light-process@next