JerapahFlow

Workflow runner with a sandboxed script engine, SQLite run history, and an admin UI.

Packages

• @jerapah-flow/server (packages/server) — Fastify runner, HTTP/cron triggers, admin REST API
• @jerapah-flow/web (packages/web) — React admin UI (Vite, DaisyUI, React Query)

Setup

pnpm install
pnpm dev

• API: http://localhost:8700
• UI (dev): http://localhost:5173

The first account created becomes admin. Later accounts are created from Users.

Script contract

Each script is async function main(ctx) and must return:

{ output, context?, skipRemaining? }

Field	Meaning
ctx.data	This step’s input (trigger payload, previous output, or DAG needs)
ctx.context	Run clipboard (plain object, default {})
ctx.config	This step’s YAML config
output	Becomes the next step’s data
context	Next snapshot of the bag. Omitted → keep incoming
skipRemaining	Stop later steps. Sibling of output/context, not inside output

Returning the full ctx is an error. Mutating ctx.data or ctx.context does not persist unless returned.

YAML SET evaluates JSONata against the full ctx; the result is output (the next step’s data). jsonata.js does the same.

DAG needs assemble this step’s data from upstream outputs. Independent steps in the same wave share a context snapshot; sibling writes to the same context key fail the run.

Optional script.meta.reads = "ctx" documents expression hosts. meta.input / meta.output / meta.context describe data, the return pipe, and clipboard keys.

Scripts

Command	Description
pnpm dev	Server + Vite together
pnpm dev:server	API/runner only
pnpm dev:web	UI only (proxies /api to :8700)
pnpm build	Production UI build
pnpm start	Serve API and built UI from :8700
pnpm migrate	Apply SQLite migrations

Environment

Variable	Default	Notes
JFLOW_JWT_SECRET	jflow-dev-secret (dev only)	Required in production.
JFLOW_SECRETS_KEY	jflow-dev-secrets-key (dev only)	Master key for named secrets. Required in production. Changing it makes existing secrets unreadable. 64 hex chars are used as a raw AES-256 key; any other string is derived with scrypt.
JFLOW_DB_PATH	packages/server/data/jerapah-flow.db	SQLite file.
REDIS_URL	redis://127.0.0.1:6379	Redis for BullMQ workflow queue. Required — the server will not start if Redis is unreachable.
REDIS_PASS	—	Optional Redis AUTH password (sent via ioredis password). Prefer this over embedding credentials in REDIS_URL so logs stay clean.
JFLOW_QUEUE_NAME	jerapah-workflows	BullMQ queue name.
JFLOW_WORKER_CONCURRENCY	5	Max parallel workflow jobs per worker process.
JFLOW_ROLE	all	Which duties this process performs: all (HTTP/admin + cron producer + worker), api (HTTP/admin + cron enqueue only), or worker (consume queue only). Use separate processes in production when you want to scale workers independently.
JFLOW_LOG_LEVEL	debug	Pino level
JFLOW_RETENTION_DAYS	30	Run history prune
JFLOW_CORS_ORIGIN	http://localhost:5173	Vite origin in dev
PORT	8700	HTTP port
NODE_ENV	—	Set production for secure cookies

Workflow runs are queued via BullMQ. HTTP and manual triggers return 202 { runId, status: "queued" } immediately; poll GET /api/runs/:id for progress (queued → running → success | failed). Cron remains an in-process producer that enqueues jobs on each tick.

Production

pnpm install
pnpm build
# Redis must be reachable at REDIS_URL (set REDIS_PASS if Redis requires AUTH)
JFLOW_JWT_SECRET=... JFLOW_SECRETS_KEY=... REDIS_URL=redis://127.0.0.1:6379 REDIS_PASS=... NODE_ENV=production pnpm start

The server serves packages/web/dist when that folder exists.