Add a node

Add a node

A node is a Docker container with code files, an image, an entrypoint, and an optional I/O JSON Schema.

.node.json shape

{
  "id": "fetch-data",
  "name": "Fetch data",
  "image": "node:22-alpine",
  "entrypoint": "node index.js",
  "setup": ["npm install --omit=dev"],
  "timeout": 60000,
  "input": {
    "type": "object",
    "properties": { "url": { "type": "string" } },
    "required": ["url"]
  },
  "output": {
    "type": "object",
    "properties": { "data": { "type": "object" } }
  }
}

• entrypoint - shell command run inside the container
• setup - commands run once before entrypoint (caches when possible)
• timeout - milliseconds, max 1h. 0 means use light-runner's 20-minute default
• input / output - JSON Schema for editor autocomplete and runtime validation

Commands

• light node info <dir> - show node config
• light node register <dir> - add the node to its parent workflow.json
• light node helpers <dir> - regenerate lp.d.ts from the I/O schema (run after manual edits to .node.json)
• light node schema <dir> - interactive prompts to edit input/output schema (also regenerates lp.d.ts)
• light node dev <dir> - generate .devcontainer/devcontainer.json from .node.json and open VS Code in the same image used in production. Add --force to regenerate

Code conventions

• The container writes its result to <workdir>/.lp-output.json (JSON only). The helper (lp.js / lp.py) handles this.
• Read input from <workdir>/.lp-input.json (JSON-encoded by light-run, seeded as a file before the container starts). The helper exposes it pre-parsed as input.
• workdir defaults to /app. Override only if the image needs a different working directory.

Constraints (light-run wire contract)

• image required, 1-300 chars
• files required, at least 1 entry, keys relative, no .., max 1024 chars each (always populated by Node.setCode() / loadDirectory())
• entrypoint optional, 1-2048 chars
• setup <= 50 entries
• Default body limit on light-run is 10 MiB - large model files need LIGHT_RUN_BODY_LIMIT bumped on the runner side