light-process

Light Process

Lightweight DAG workflow engine for orchestrating code in Docker containers. Delegates container execution to light-run.

Documentation - Quick Start - Use Cases - npm

Use Cases

Per-tenant report pipelines - SaaS sending a PDF per customer: fetch data (Python) -> transform (R) -> render PDF (Node) -> send email. One POST /run per customer, full Docker isolation per step, no shared state. Temporal is too heavy, n8n has no real container execution.

Security automation chains - Run Trivy, nuclei, nmap in sequence with conditional branching: if a CVE is found, trigger a deeper scan. Each scanner in its own container, self-hosted, HTTP-triggered. No GitHub Actions cloud dependency, no Bash fragility.

Polyglot processing pipelines - Node scraper, Python parser, Go enricher, shell uploader - all chained. No virtualenvs, no global installs, no runtime conflicts. Each step gets only the deps it needs. Mixed runtimes that LangChain and Prefect cannot handle natively.

Run untrusted code - Execute user-submitted scripts in containers isolated upstream by light-run (dropped caps, PID limits, isolated network, optional gVisor). Perfect for coding playgrounds, graders, or plugin systems where you cannot trust the input.

Install

light-process is the DAG orchestrator. Container execution is delegated to a separate service called light-run. Install both:

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

Requires Node 20+ and Docker running on the same host as light-run.

Prefer a project-local install? Drop the -g and call the CLI through npx (the binaries land in node_modules/.bin, not your PATH, so plain light will not resolve):

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

npm install -g github:enixCode/light-process#alpha
npm install -g github:enixCode/light-run#alpha

Claude Code plugin

If you use Claude Code, light-process ships a plugin with skills covering the architecture, workflow scaffolding, node creation, remote management, and runner setup. Install via the public marketplace:

/plugin marketplace add enixCode/plugins
/plugin install light-process@enix

The plugin lives in .claude-plugin/plugin.json + skills/ of this repo. Skills load on demand based on what you ask Claude (no overhead until a relevant request).

Quick Start

One command. light serve auto-spawns a local light-run when LIGHT_RUN_URL is unset:

light serve                     # boots light-run + the orchestrator, streams both logs

Or explicitly, with the runner on a separate host (prod):

# Host 1 - the runner
light-run serve --token $(openssl rand -hex 32) --port 3001

# Host 2 - the orchestrator
export LIGHT_RUN_URL=http://runner-host:3001
export LIGHT_RUN_TOKEN=<same token as above>
light serve

Other useful commands:

light doctor                    # check Node + light-run connectivity
light init my-project           # scaffold a project
cd my-project
light run example               # run the example workflow

light serve --install will also npm i -g @enixcode/light-run for you if the binary is missing.

Output:

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

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

[ok] 2108ms

Your First Workflow

After light init my-project, you get this:

my-project/
  example/
    workflow.json        # the DAG: which nodes exist, how they link
    hello/
      .node.json         # node config (Docker image, entrypoint, I/O)
      index.js           # your code
      lp.js              # helper - provides input and send()
      lp.d.ts            # auto-generated types for editor autocomplete

A node is just a folder with code that runs in a Docker container. A workflow is a workflow.json that wires nodes together. That's it.

Open example/hello/index.js:

const { input, send } = require('./lp');
console.error('Input:', JSON.stringify(input));
send({ hello: 'world', input });