commit 15740a054ff4cf32aac7e6a694fe5c1c76077f75 Author: Lucas Winther Date: Fri Oct 30 00:14:46 2026 +0100 chore: bootstrap agent-ready docs, rules, spec and research Adds AGENTS.md (clean-room and Bun rules), pointer files, agent permission configs, docs tree, the STaurtomation design spec (draft) and sanitized licensing/competitor research. Co-Authored-By: Claude Opus 5.5 diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..cafabe9 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,34 @@ +{ + "permissions": { + "allow": [ + "Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)", "Bash(git show:*)", + "Bash(git branch --list:*)", "Bash(git rev-parse:*)", + "Bash(git add:*)", "Bash(git commit:*)" + ], + "ask": [ + "Bash(git push:*)", "Bash(git merge:*)", "Bash(git rebase:*)", "Bash(git switch:*)", + "Bash(git restore:*)", "Bash(git commit --amend:*)", "Bash(rm:*)", + "Bash(bun add:*)", "Bash(bun remove:*)", "Bash(bun update:*)", "Bash(bun upgrade:*)", + "Bash(bunx:*)", "Bash(npx:*)", "Bash(git clone:*)" + ], + "deny": [ + "Bash(git push --force:*)", "Bash(git push -f:*)", "Bash(git push --force-with-lease:*)", + "Bash(git reset --hard:*)", "Bash(git clean:*)", "Bash(git add -f:*)", "Bash(git add --force:*)", + "Bash(git commit --no-verify:*)", "Bash(git commit -n:*)", + "Bash(rm -r:*)", "Bash(rm -R:*)", "Bash(rm -rf:*)", "Bash(rm -fr:*)", "Bash(rm -Rf:*)", + "Bash(rm -fR:*)", "Bash(rm --recursive:*)", "Bash(sudo:*)", + "Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)", + "Bash(git clone https://github.com/n8n-io:*)", "Bash(git clone https://github.com/kestra-io:*)", + "Bash(git clone https://github.com/windmill-labs:*)", "Bash(git clone https://github.com/activepieces:*)", + "Bash(git clone git@github.com:n8n-io:*)", "Bash(git clone git@github.com:kestra-io:*)", + "Bash(git clone git@github.com:windmill-labs:*)", "Bash(git clone git@github.com:activepieces:*)", + "Bash(npm view n8n:*)", "Bash(npm pack n8n:*)", "Bash(npm view @n8n:*)", "Bash(npm pack @n8n:*)", + "Bash(npm view @activepieces:*)", "Bash(npm pack @activepieces:*)", + "Bash(bun add n8n:*)", "Bash(bun add @n8n:*)", "Bash(bun add @n8n_io:*)", "Bash(bun add @activepieces:*)", + "WebFetch(domain:raw.githubusercontent.com)", "WebFetch(domain:unpkg.com)", "WebFetch(domain:cdn.jsdelivr.net)", + "Read(**/node_modules/n8n-workflow/**)", "Read(**/node_modules/n8n-core/**)", + "Read(**/node_modules/n8n-nodes-base/**)", "Read(**/node_modules/@n8n/**)", + "Read(**/node_modules/@activepieces/**)" + ] + } +} diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 0000000..5542eff --- /dev/null +++ b/.codex/config.toml @@ -0,0 +1,2 @@ +sandbox_mode = "workspace-write" +approval_policy = "on-request" diff --git a/.codex/rules/project.rules b/.codex/rules/project.rules new file mode 100644 index 0000000..51664d2 --- /dev/null +++ b/.codex/rules/project.rules @@ -0,0 +1,23 @@ +# Deny +prefix_rule(pattern = ["git", "push", ["--force", "-f", "--force-with-lease"]], decision = "forbidden", + justification = "Force-push rewrites shared history.") +prefix_rule(pattern = ["git", "reset", "--hard"], decision = "forbidden", justification = "Discards work.") +prefix_rule(pattern = ["git", "clean"], decision = "forbidden", justification = "Deletes untracked files.") +prefix_rule(pattern = ["git", "add", ["-f", "--force"]], decision = "forbidden", + justification = "Stages ignored files, e.g. secrets.") +prefix_rule(pattern = ["git", "commit", ["--no-verify", "-n"]], decision = "forbidden", justification = "Skips hooks.") +prefix_rule(pattern = ["rm", ["-r", "-R", "-rf", "-fr", "-Rf", "-fR", "--recursive"]], decision = "forbidden", + justification = "Recursive delete.") +prefix_rule(pattern = ["sudo"], decision = "forbidden", justification = "No privilege escalation.") +prefix_rule(pattern = ["git", "clone", ["https://github.com/n8n-io/n8n", "https://github.com/n8n-io/n8n.git", + "https://github.com/kestra-io/kestra", "https://github.com/windmill-labs/windmill", + "https://github.com/activepieces/activepieces"]], decision = "forbidden", + justification = "Clean room: never fetch source of the products we supersede (AGENTS.md).") +prefix_rule(pattern = [["npm", "bun"], ["view", "pack", "add"], ["n8n", "n8n-workflow", "n8n-core", "n8n-nodes-base"]], + decision = "forbidden", justification = "Clean room: never fetch or depend on n8n packages.") +# Ask +prefix_rule(pattern = ["git", ["push", "merge", "rebase", "switch", "restore", "clone"]], decision = "prompt") +prefix_rule(pattern = ["git", "commit", "--amend"], decision = "prompt") +prefix_rule(pattern = ["rm"], decision = "prompt") +prefix_rule(pattern = ["bun", ["add", "remove", "update", "upgrade"]], decision = "prompt") +prefix_rule(pattern = [["bunx", "npx"]], decision = "prompt") diff --git a/.gemini/settings.json b/.gemini/settings.json new file mode 100644 index 0000000..cd8341e --- /dev/null +++ b/.gemini/settings.json @@ -0,0 +1,20 @@ +{ + "tools": { + "allowed": [ + "run_shell_command(git status)", "run_shell_command(git diff)", "run_shell_command(git log)", + "run_shell_command(git show)", "run_shell_command(git branch --list)", + "run_shell_command(git add)", "run_shell_command(git commit)" + ], + "exclude": [ + "run_shell_command(git push --force)", "run_shell_command(git push -f)", + "run_shell_command(git push --force-with-lease)", "run_shell_command(git reset --hard)", + "run_shell_command(git clean)", "run_shell_command(git add -f)", "run_shell_command(git add --force)", + "run_shell_command(git commit --no-verify)", "run_shell_command(git commit -n)", + "run_shell_command(rm -r)", "run_shell_command(rm -R)", "run_shell_command(rm -rf)", + "run_shell_command(rm -fr)", "run_shell_command(rm -Rf)", "run_shell_command(sudo)", + "run_shell_command(git clone https://github.com/n8n-io)", "run_shell_command(git clone https://github.com/kestra-io)", + "run_shell_command(git clone https://github.com/windmill-labs)", "run_shell_command(git clone https://github.com/activepieces)", + "run_shell_command(npm view n8n)", "run_shell_command(npm pack n8n)", "run_shell_command(bun add n8n)" + ] + } +} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..61cf1de --- /dev/null +++ b/.gitignore @@ -0,0 +1,11 @@ +node_modules/ +dist/ +.env +.env.* +!.env.example +CLAUDE.local.md +.claude/settings.local.json +.worktrees/ +*.sqlite +*.sqlite-journal +coverage/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..46825ff --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,97 @@ +# STaurtomation + +Clean-room, AGPL-3.0-or-later workflow automation platform meant to supersede n8n, Kestra, Windmill +and Activepieces. Planned stack: TypeScript on Bun 1.3, React + React Flow editor, SQLite/Postgres. +**No code exists yet** — the approved design is `docs/specs/001-staurtomation.md`; read it first. + +`AGENTS.md` is the single source of truth for agents here. `CLAUDE.md` and `GEMINI.md` only point here. +Deeper context on demand: `docs/ARCHITECTURE.md`, `docs/DECISIONS.md`, `docs/TODO.md`, `docs/research/`. + +## Clean room — read before anything else + +This project must never be struck down: it supersedes those tools, it does not copy them. +Full rules: spec §3.2. The ones agents break: + +- **Never read source code** of n8n, Kestra, Windmill or Activepieces — no cloning, no browsing + their GitHub source files, no `npm view`/`npm pack`/unpacking their packages, no reading + `node_modules` copies of `n8n-workflow`, `n8n-core`, `n8n-nodes-base`, `@n8n/*`, `@activepieces/*`. +- **Allowed:** their public documentation sites, published specs (e.g. Windmill OpenFlow), workflow + files exported from a running instance, observed behaviour of a running instance. +- **Never copy code** from any repository unless it is permissively licensed, AGPL-compatible, and + recorded in `THIRD_PARTY.md` (source URL, license, commit). Nothing from the four products at all. +- **Never add those products' packages as dependencies.** Dependencies must be AGPL-compatible + (MIT, BSD, ISC, Apache-2.0, MPL-2.0, (L)GPL-3.0, AGPL-3.0); ask first for any new one. +- **Own naming.** Identifiers, file layout and module names follow STaurtomation conventions. n8n + node type strings (`n8n-nodes-base.httpRequest`) appear only inside importer mapping tables. +- Every PR touching importers, expression compatibility or compatibility layers needs a provenance + note (which docs/exports/behaviour it was based on) and human sign-off. +- If you realise you were exposed to prohibited source for an area: stop, record it in the PR, and + do not implement that area. +- Never use the products' names as or in our product, package or node names. "Imports n8n workflows" is fine. + +## Commands + +TODO(maintainer): confirm commands once tooling exists (no `package.json` yet) — planned: `bun install --frozen-lockfile`, `bun test`, `bunx tsc --noEmit`. + +## Bun conventions (from `bun init`) + +- `bun `, `bun test`, `bun build`, `bun install`, `bun run`, `bunx` — never node, npm, jest, + vitest, webpack, esbuild, ts-node. Bun loads `.env` itself; no dotenv. +- `Bun.serve()` routes + WebSockets, not express. `bun:sqlite`, `Bun.sql` (Postgres), `Bun.redis`, + built-in `WebSocket`, `Bun.file`, `` Bun.$`cmd` `` — not better-sqlite3, pg, ioredis, ws, execa. +- Frontend: HTML imports served by `Bun.serve()` (they bundle `.tsx`/CSS/Tailwind). No Vite. +- Bun API docs: `node_modules/bun-types/docs/**.mdx` once dependencies are installed. + +## Workflow + +Required skills: `superpowers`, `impeccable`. Check at session start; install if missing. +Specs → `docs/specs/NNN-slug.md` (permanent). Plans → `docs/plans/NNN-slug.md` while in progress; +`git rm` them before opening a merge request — the spec is the record. +(Overrides the superpowers default paths.) + +Anything beyond a trivial fix: brainstorm → spec (sign-off) → plan (sign-off) → TDD → review. +TDD means failing test first, watch it fail, minimal code, watch it pass, commit. +Tick plan checkboxes as you go so an interrupted session is resumable. +Trivial changes (typo, version bump, one-line config): say "trivial, skipping spec" and proceed. + +Use impeccable for user-facing UI — `craft` for new, `audit`/`polish` on existing, +`harden` before shipping. Design context: `PRODUCT.md`, `DESIGN.md`. + +## Rules + +- Every source file starts with `// SPDX-License-Identifier: AGPL-3.0-or-later`. +- No feature is ever gated by edition, license key, user count or payment. +- Importers never drop data: unsupported nodes become visible placeholders and block activation. +- Permission checks happen server-side on every route; the UI only mirrors them. + +## Boundaries + +Never commit `.env`, secrets, or credentials. +Never force-push, rewrite pushed history, or commit directly to `main`. + +Ask first: new runtime dependencies · public API or schema/migration changes · auth, credential +encryption, runner isolation, licensing files · anything destructive (`rm -rf`, `git reset --hard`, +DB resets) · work the approved plan does not cover. + +If the task turns out much larger than the plan assumed: stop, report, re-plan. + +## Docs duties + +Same commit as the code, not "later": +- `docs/ARCHITECTURE.md` — when a module, boundary, or data flow changes. +- `docs/DECISIONS.md` — append-only; any choice a future maintainer would reverse-engineer. +- `docs/TODO.md` — anything noticed and deliberately not fixed. No `TODO` comments in source. +- `docs/PERMISSIONS.md` — together with every tool permission file (`.claude/settings.json`, + `.codex/`, `.gemini/settings.json`), in one commit. + +## Git + +Remote: `origin` → Gitea `lucasw89/STaurtomation`. Branches: `feat|fix|chore/`. +Commits: Conventional Commits. Small, each leaving tests green. + +## Done means verified + +Do not report success on work you have not run. Before saying done: +tests run *in this session* and seen passing · lint and typecheck clean · matches the approved spec · +docs duties complete · `git status` clean and the diff is only what you intended. +"It should work" is not verification. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..20275b8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,9 @@ +# CLAUDE.md + +**`AGENTS.md` is the single source of truth for this repository.** Read it now and follow it exactly. + +@AGENTS.md + +This file exists only so Claude Code finds the rules, and for Claude-specific configuration that +AGENTS.md cannot express. It contains no project rules of its own — add those to `AGENTS.md`. +If anything here ever conflicts with `AGENTS.md`, `AGENTS.md` wins. diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 0000000..50b9113 --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,5 @@ +# Design + +No design system yet. Stack decided (spec §4.1): React, React Flow canvas, shadcn/ui components, +Tailwind. Create the visual direction with impeccable (`craft`) before the first UI work and record +tokens, typography and component rules here. Do not imitate the look of n8n or the other products. diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..a97a85e --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,7 @@ +# GEMINI.md + +**`AGENTS.md` is the single source of truth for this repository.** Read `./AGENTS.md` before doing +anything else and follow it exactly. + +This file exists only so Gemini CLI finds the rules. It contains no project rules of its own — add +those to `AGENTS.md`. If anything here ever conflicts with `AGENTS.md`, `AGENTS.md` wins. diff --git a/PRODUCT.md b/PRODUCT.md new file mode 100644 index 0000000..50cab05 --- /dev/null +++ b/PRODUCT.md @@ -0,0 +1,10 @@ +# Product + +STaurtomation is a self-hosted visual workflow automation tool. Users (spec §1): +- **Homelabbers** — notifications, OpenClaw, smart home, small scheduled jobs; single-box install. +- **University staff, often non-technical** — build automations visually, sign in via SAML/OIDC. +- **Companies prototyping** — ease of use, low maintenance, scheduled AI queries. + +Must feel easy to non-developers: code is available, never required. Core moments: building on the +canvas, testing with pinned data and seeing each node's input/output, reviewing import reports, +approving AI-assistant diffs, and noticing security updates. diff --git a/README.md b/README.md new file mode 100644 index 0000000..c5e5a76 --- /dev/null +++ b/README.md @@ -0,0 +1,4 @@ +# STaurtomation + +Open, clean-room workflow automation (AGPL-3.0-or-later). Design: `docs/specs/001-staurtomation.md`. +Contributors and AI agents: start with [`AGENTS.md`](AGENTS.md). diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..16848aa --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,32 @@ +# Architecture + +How `STaurtomation` is built today. Update in the same commit as any structural change. + +## Overview +No code exists yet. The target architecture is specified in `docs/specs/001-staurtomation.md` §4: +one Bun process serving the React editor, the REST/WebSocket API, scheduler and workflow engine; +separate language runners (Bun/TypeScript, Python first) that connect to the server over WebSocket, +receive jobs and stream results back. Replace this section with reality as modules land. + +## Map +| Path | Responsibility | +|---|---| +| `docs/specs/` | Permanent specs; `001-staurtomation.md` is the product design | +| `docs/research/` | Sanitized licensing and competitor research (clean-room safe) | +| `docs/plans/` | Transient implementation plans | + +## Data flow +Planned (spec §4.4): trigger → server enqueues execution → runner executes nodes on lists of items +→ per-node input/output persisted (subject to retention/redaction) → editor shows results. + +## External dependencies +Planned: SQLite (single box) or PostgreSQL; optional Redis for HA; optional container runtime for +isolated job execution; optional S3-compatible storage for binary data. + +## Invariants +- No code from n8n, Kestra, Windmill or Activepieces; no dependency on their packages (spec §3.2). +- No feature gated by edition, key, user count or payment. +- Imports never silently drop nodes or data. + +## Known rough edges +None yet — see `docs/TODO.md`. diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md new file mode 100644 index 0000000..c0ccbc3 --- /dev/null +++ b/docs/DECISIONS.md @@ -0,0 +1,50 @@ +# Decisions + +Append-only. Never edit or delete an entry — supersede it with a new one that links back. +One entry per decision a future maintainer would otherwise have to reverse-engineer. +No index: `grep -n '^## ' docs/DECISIONS.md` lists every entry (date, title, line number). + +## 2026-10-30 — Release 1 is homelab-ready, without the community-node compatibility layer +**Status:** accepted +**Context:** Reimplementing n8n's node-facing interface is the project's highest legal-risk area. +**Decision:** Release 1 targets single-box homelab installs (spec §10). The n8n importer ships as +best effort with clear warnings; the community-node layer ships only after legal review. +**Alternatives:** Waiting for legal review before any release (delays everything). +**Consequences:** Imported workflows that use community nodes get placeholders until Release 3. + +## 2026-10-30 — AI agents may build every area, behind mandatory guards +**Status:** accepted +**Context:** The project is built mainly by AI agents, whose training data likely includes the +public source of the products being superseded. +**Decision:** Allowed, with CI similarity scanning, per-PR provenance notes, a dependency denylist, +agent tooling restrictions and human sign-off on importer/compat work (spec §3.2 rule 5a). +**Alternatives:** Human-only implementation of high-risk areas (not staffable). +**Consequences:** CI must carry the similarity and denylist guards before high-risk work starts. + +## 2026-10-29 — License AGPL-3.0-or-later with a CLA +**Status:** accepted +**Context:** Owner wants the project to stay open while retaining copyright and relicensing freedom. +**Decision:** AGPL-3.0-or-later for everything; outside contributions require a CLA. +**Alternatives:** MIT (allows closed forks); GPL-3.0 (hosted-modification gap); DCO only (no relicensing rights). +**Consequences:** Only AGPL-compatible dependencies; CLA tooling needed before accepting outside PRs. + +## 2026-10-29 — Bun-native stack, React editor, Better Auth +**Status:** accepted +**Context:** n8n community nodes are TypeScript/npm packages; owner wants Bun + TypeScript. +**Decision:** Bun with `Bun.serve()` and Bun built-ins (per `bun init` conventions); React + React +Flow + shadcn/ui + Tailwind via Bun HTML imports; Better Auth for authentication, with Passport as +fallback if its SAML/SCIM support proves immature. +**Alternatives:** Next.js (redundant server, public-site oriented); Vite and Hono (superseded by Bun +built-ins); Passport first (Express-centric). +**Consequences:** Verify Better Auth on Bun before building auth (spec §12). + +## 2026-10-29 — Adopt AGENTS.md as single source of truth +**Status:** accepted +**Context:** Agents had no durable project context and no consistent workflow between sessions. +**Decision:** `AGENTS.md` is canonical; `CLAUDE.md`/`GEMINI.md` are pointers. Specs are permanent in +`docs/specs/`. Plans live in `docs/plans/` only while work is in progress and are removed before the +merge request. Both override the superpowers default paths. +**Alternatives:** Per-tool rule files (drift, synchronisation debt); no rules file (agents re-explore +the repo every session — measurably slower and more tokens). +**Consequences:** Rule changes happen in one file; pointer files must stay thin. Plans are working +artefacts: kept after merge they go stale and contradict the code, so the spec is the record. diff --git a/docs/PERMISSIONS.md b/docs/PERMISSIONS.md new file mode 100644 index 0000000..d0208c9 --- /dev/null +++ b/docs/PERMISSIONS.md @@ -0,0 +1,47 @@ +# Agent permissions + +Source of truth for what AI coding agents may run here. Tool files are renderings of this page: +`.claude/settings.json`, `.codex/config.toml`, `.codex/rules/project.rules`, `.gemini/settings.json`. +Change this page and every tool file in the same commit. + +## Verified commands + +Run on 2026-10-30 while bootstrapping. Only `worked` rows may appear in a tier, a tool file, or `AGENTS.md` Commands. + +| Command | Result | +|---|---| +| `git status` | worked | +| `git --version` | worked (2.47.3) | +| `bun --version` | worked (1.3.14) | +| `bun install --frozen-lockfile` | not run — no `package.json` yet | +| `bun test` | not run — no code yet | +| `bunx tsc --noEmit` | not run — no TypeScript installed yet | + +TODO(maintainer): confirm every row above that is not worked once tooling exists, then add them to Allow. + +## Tiers + +| Tier | Commands | Why | +|---|---|---| +| Allow | `git status`, `git diff`, `git log`, `git show`, `git branch --list`, `git rev-parse`, `git add`, `git commit` | Inspection and the verified dev loop; no prompt needed. | +| Ask | `git push`, `git merge`, `git rebase`, `git switch`, `git restore`, `git commit --amend`, `git clone`, `rm`; `bun add/remove/update/upgrade`; `bunx`, `npx` | Leaves the machine, rewrites work, downloads code, or changes dependencies — a human decides. | +| Deny | force pushes, `git reset --hard`, `git clean`, `git add -f`, `git commit --no-verify`/`-n`, recursive `rm`, `sudo`; reading `.env`, `.env.*`, `secrets/**` | Destroys work, skips checks, or exposes secrets. | +| Deny (clean room) | cloning `n8n-io`, `kestra-io`, `windmill-labs`, `activepieces` repos; `npm view/pack` and `bun add` of n8n/Activepieces packages; reading those packages under `node_modules`; WebFetch of `raw.githubusercontent.com`, `unpkg.com`, `cdn.jsdelivr.net` (raw source/package hosts) | Enforces AGENTS.md "Clean room" (spec §3.2). | + +## Known gaps +- Allowlists save prompts; they are not a security boundary. Use the tool's sandbox for isolation. +- Prefix rules are bypassable: `git -C dir push`, flags placed later (`git push origin main --force`), + `+refspec` pushes. Claude Code's `:*` matches at a word boundary, so each flag cluster must be + listed — which is why `git clean` is denied whole and `rm` always asks. +- Clean-room denies are best effort: browsing github.com source pages, other mirrors, or `curl` are + not blocked (Claude Code WebFetch rules are per domain, and github.com also hosts allowed material). + The CI similarity scan and dependency denylist are the real guard (TODO). +- The raw-host WebFetch denies also block legitimate permissive sources on those hosts; ask a human + to approve a one-off fetch when needed. +- Allowed test, lint, and build commands run code from the repo; an agent that can edit + `package.json` or the tests can run anything through them. +- Denying reads of `.env` does not stop a script that opens it itself, and git can print staged or + committed secrets. `git add -f` is denied so an agent cannot stage an ignored secret. +- Codex: `approval_policy` here can loosen a stricter user setting; `.git/` is read-only in its + sandbox, so commits ask for escalation. Codex and Gemini cannot deny file reads. +- Gemini: no Ask tier (anything not allowed asks); `tools.exclude` is deprecated but the only project-level deny. diff --git a/docs/TODO.md b/docs/TODO.md new file mode 100644 index 0000000..3b04a8e --- /dev/null +++ b/docs/TODO.md @@ -0,0 +1,32 @@ +# TODO + +Durable backlog. Agents append here instead of leaving `TODO` comments in source. +Small, specific, independently actionable. Remove only when actually done. + +## Now +- [ ] Owner: approve `docs/specs/001-staurtomation.md` (set `status: approved`). +- [ ] Write the implementation plan for Phase 0 + Release 1 (`docs/plans/001-staurtomation.md`). +- [ ] Phase 0: add `LICENSE` (AGPL-3.0 full text), `CONTRIBUTING.md`, CLA, `THIRD_PARTY.md`, PR template with provenance note. +- [ ] Phase 0: CI on Gitea Actions — tests, typecheck, SPDX header check, dependency-license allowlist, dependency denylist, code-similarity scan (spec §3.2 rule 5a). +- [ ] Once `package.json` exists: verify commands and fill `AGENTS.md` Commands + `docs/PERMISSIONS.md`. + +## Next +- [ ] Verify Better Auth SAML/SCIM maturity and Bun compatibility (spec §12.1). +- [ ] Measure Bun compatibility of popular n8n community nodes (spec §12.2) — without reading n8n source. +- [ ] CI check that `AGENTS.md`, pointer files and docs paths exist; fail if `AGENTS.md` > 150 lines. + +## Someday +- [ ] Owner: Entra ID test tenant + CI credentials (needed by Release 2). +- [ ] Owner: legal review of the compatibility-layer approach (blocks Release 3). + +## Recurring +- [ ] Maintain `AGENTS.md`: + - **Add a rule only in response to a real failure.** When an agent repeatedly gets something wrong, + that is a gap; add one line, ideally with a code example. Do not pre-empt hypothetical mistakes. + - **Update in the same PR as the convention change.** A stale rules file is worse than none — it + actively misleads. + - **Prune quarterly.** Delete rules whose convention has changed or whose mistake no longer occurs. + - **Optional, cheap validation:** run the same task twice in clean sessions, with and without the + file, and compare steps and token use. + +## Known issues diff --git a/docs/plans/README.md b/docs/plans/README.md new file mode 100644 index 0000000..c4ace6f --- /dev/null +++ b/docs/plans/README.md @@ -0,0 +1,11 @@ +# Plans + +Implementation plans from the superpowers writing-plans workflow. **Transient:** a plan lives only on +its feature branch and is removed with `git rm` before the merge request is opened. This README stays. + +- Naming: `NNN-short-slug.md`, matching its spec number. +- Links back to its spec. Bite-sized checkbox tasks with exact file paths, test commands, and + commit checkpoints. +- Written for an engineer with zero context for this codebase — spell out the obvious. +- Tick checkboxes as you go so another agent can resume an interrupted session. +- Front matter: `status: draft | approved | in-progress`. There is no `done` — a finished plan is deleted. diff --git a/docs/research/README.md b/docs/research/README.md new file mode 100644 index 0000000..5ff00f6 --- /dev/null +++ b/docs/research/README.md @@ -0,0 +1,20 @@ +# Research + +Background research ported from earlier work (2026-10-29) and sanitized for clean-room use. Details learned from the source code of n8n, Kestra, Windmill or Activepieces have been removed. What remains comes from license texts, public docs, pricing pages, legal sources and community discussion. Nothing here is legal advice. + +## Reports + +- [reports/n8n-gated-features-reimplementation.md](reports/n8n-gated-features-reimplementation.md): n8n's licensing (SUL and Enterprise License), the legal paths for rebuilding its paid features, and why an independent clean-room product is the viable commercial route. +- [reports/kestra-windmill-activepieces-comparison.md](reports/kestra-windmill-activepieces-comparison.md): licensing, free versus paid features, operations and community health of Kestra, Windmill and Activepieces compared with n8n. + +## Notes + +- [notes/n8n-licensing-legal.md](notes/n8n-licensing-legal.md): n8n license clauses, case law, anti-circumvention, trademark and enforcement history. +- [notes/n8n-feature-feasibility.md](notes/n8n-feature-feasibility.md): feature-by-feature feasibility of providing n8n's gated features (SSO, RBAC, audit, Git sync and others) from documented behaviour. +- [notes/kestra.md](notes/kestra.md): Kestra licensing, OSS versus Enterprise features, pricing, operations and community. +- [notes/windmill.md](notes/windmill.md): Windmill licensing and its history, CE versus EE features, pricing, self-hosting and community. +- [notes/activepieces.md](notes/activepieces.md): Activepieces MIT and Enterprise split, plans and pricing, self-hosting and community. + +## Intentionally excluded + +The original research also contained architecture notes produced from a source-code read of n8n, covering how its feature gating is implemented. They were left out on purpose and must not be brought into this repository. STaurtomation contributors must not read the source code of n8n, Kestra, Windmill or Activepieces, or of forks of them such as the sreent/n8n "tuflow" fork, and must not read descriptions derived from that source. diff --git a/docs/research/notes/activepieces.md b/docs/research/notes/activepieces.md new file mode 100644 index 0000000..8946d37 --- /dev/null +++ b/docs/research/notes/activepieces.md @@ -0,0 +1,172 @@ +> Ported from earlier research (2026-10-29) and sanitized for clean-room use: source-code-derived details removed. Not legal advice. + +# Activepieces as a self-hosted n8n alternative (as of late Oct 2026) + +Method note: Licensing facts come from the repository's LICENSE files and GitHub metadata/API (stars, forks, releases, LICENSE commit history). Gating, ops and env-var facts come from the official documentation (activepieces.com/docs) and the pricing page (activepieces.com/pricing), fetched 2026-10-29. Third-party reviews are marked as such. "Verified" means read in a primary public source. "Inference" means my reading of the docs that no source states directly. Clean-room note: the Activepieces enterprise code is proprietary; STaurtomation contributors must not read or copy it, nor the MIT core's implementation, and should work from documented behaviour only. + +## 1. License (MIT core + commercial EE), license history + +### Takeaway +This is an open-core repo. Everything is MIT except two enterprise ("ee") directories named in the root LICENSE, which fall under a proprietary "Activepieces Enterprise license". Production use of that code needs a paid subscription; dev and test use is free. The split has been in place since Feb 2023 and has not changed in substance since. There is no BSL/SSPL-style relicensing of the core (unlike n8n's Sustainable Use License). The "conflicting sources" problem has a simple cause: the MIT Community Edition is the core alone (the pricing FAQ calls it "the automation core on its own"), without SSO, roles, audit logs, git sync, secret managers or embedding. Marketing copy that calls Activepieces "fully MIT" leaves the enterprise directories out. + +### Cited Findings +- Root LICENSE: all content under two named enterprise directories of the repository "is licensed under the license defined in" the enterprise LICENSE file, and "Content outside of the above mentioned directories … is available under the "MIT Expat" license". Copyright line: "(c) 2020-2024 Activepieces Inc." GitHub's API reports the SPDX ID as `NOASSERTION` because the license is mixed. — LICENSE file in [activepieces/activepieces](https://github.com/activepieces/activepieces) +- Enterprise LICENSE ("Activepieces Enterprise license"): the software "may only be used in production, if you … have agreed to … the Activepieces Subscription Terms of Service … and otherwise have a valid Activepieces Enterprise license for the correct number of user seats." You may modify it and publish patches, but Activepieces keeps the rights to those patches, and they may only be used with a valid license. "you may copy and modify the Software for development and testing purposes, without requiring a subscription." Otherwise "it is forbidden to copy, merge, publish, distribute, sublicense, and/or sell the Software." — enterprise LICENSE file in [activepieces/activepieces](https://github.com/activepieces/activepieces) +- Official docs: "Activepieces' core is released as open source under the MIT license and enterprise / cloud editions features are released under Commercial License … Using the enterprise features … with a self-hosted instance requires an Activepieces license." — [docs: license](https://www.activepieces.com/docs/about/license) +- LICENSE git history: created 2022-12-07 as MIT. "chore(license): add ee license" on 2023-02-17, with follow-ups on 2023-02-20. "merge ee repository" on 2023-10-07 (EE code had lived in a separate repo before that). An editions wording change on 2023-11-14. A year bump on 2024-02-11. A path update on 2024-02-15. No commits to either LICENSE file since Feb 2024. — [GitHub commits for LICENSE](https://github.com/activepieces/activepieces/commits/main/LICENSE) +- The vendor's n8n comparison blog (Jul 2025) calls Activepieces "fully open source under the MIT license" and n8n "Fair Code (commercial restricted)". — [activepieces.com blog](https://www.activepieces.com/blog/activepieces-vs-n8n) + +### Inferences +- The license structure has been stable for about 2.7 years (Feb 2024 to Oct 2026), and the substantive MIT/EE split dates to Feb 2023. I found no 2025-2026 license change. The real change happened in pricing and packaging (see section 2). +- The EE license forbids production use without a subscription, and patching gate checks for production use is explicitly forbidden. The core is MIT, so features can legally be re-implemented independently. For STaurtomation, any re-implementation must be clean-room from documented behaviour; do not read the EE or core code. +- The "fully MIT" vendor wording overstates things. The accurate phrase is "MIT core, proprietary EE modules in the same repo" (open core, similar to GitLab's model). + +### Gaps +- I did not read the full text of activepieces.com/terms (the Subscription ToS the EE license references). +- I did not check the separate pre-Oct-2023 EE repository for its license history. + +## 2. Free Community Edition vs paid plans, pricing + +### Takeaway +The cloud ladder as of Oct 2026 is Free ($0, 1,000 credits/mo, up to 5 users), Plus ($20/mo flat, 10k credits), Team ($200/mo flat, 50k credits, 25 users, SSO + standard roles, unlimited projects), Ultimate (custom, yearly), Embed (from $36k/yr), and "Enterprise control" (custom, on-prem/air-gapped). Docs say every plan can also run self-hosted. Plus and Team are bought in-app with no key. Custom and Enterprise plans need a license key, and only with `AP_EDITION=ee`. The Community Edition (default, `AP_EDITION` unset) is the free MIT core, with no run or credit caps, but it cannot take a license key later. + +### Cited Findings +- Pricing page plans: Free $0 (1,000 credits/month, up to 5 users, "Free forever, no card"). Plus $20/month flat (10,000 credits, up to 5 users, BYO AI keys, team analytics, API and SDK). Team $200/month flat (50,000 credits, 25 users included, "Unlimited projects, SSO and standard roles, global connections, email support"). Ultimate custom (yearly, unlimited users, "Dedicated workers, SCIM and custom roles, releases and Git Sync, audit logs and secrets", plus custom terms, branding, platform governance, event streaming, private pieces, per-project credit usage). Embed "From $36k/year" (white-label builder, SDK, your pieces/templates). "Enterprise control": custom, "Run on your own servers or fully air-gapped". Overage $0.007/credit on Plus and Team. All tiers include unlimited flows, agents, tables, MCPs, and API access. — [activepieces.com/pricing](https://www.activepieces.com/pricing) (fetched 2026-10-29) +- The pricing FAQ says self-hosting "decides where Activepieces runs, not what it can do," and calls the Community Edition "the automation core on its own." — [activepieces.com/pricing](https://www.activepieces.com/pricing) +- "Activepieces runs on the free plan by default. Every plan on the pricing page is available self-hosted … Upgrading to Plus or Team? … Subscribe from inside the app and your plan applies automatically, with no key to enter … This page is for custom and enterprise plans." The key is activated under Platform Admin → Billing, with no restart needed. — [docs: Enterprise license key](https://www.activepieces.com/docs/install/configure-operate/enterprise-license) +- Self-host compose guide: "Set the edition … `AP_EDITION=ee` … Without it you get the Community edition, and you will not be able to activate a license key later." Hobby single-container installs on embedded PGLite "cannot run Enterprise at all." — [docs: docker-compose](https://www.activepieces.com/docs/install/options/docker-compose), [docs: enterprise license](https://www.activepieces.com/docs/install/configure-operate/enterprise-license) +- Third-party one-click installs (AWS/GCP/Railway/Elestio/Easypanel/PikaPods) "install the free Community edition". — [docs: install overview](https://www.activepieces.com/docs/install/overview) +- "On self-hosted installations plans don't apply" to concurrency. Per-project concurrency enforcement is off by default (`AP_PROJECT_RATE_LIMITER_ENABLED=false`). — [docs: limits](https://www.activepieces.com/docs/install/reference/limits) +- OLDER (Jul 2025): the vendor blog listed Free at 1,000 tasks/mo + 200 AI credits and "Basic" at $25/mo (unlimited executions, 10 active flows). Older plan names and prices are therefore stale. — [activepieces.com blog, 2025-07-30](https://www.activepieces.com/blog/activepieces-vs-n8n) +- OLDER (Jul 2025): HN post "We just made automation runs/tasks unlimited and Launched agen[ts]". — [HN Algolia](https://hn.algolia.com/api/v1/search?query=activepieces&tags=story) (story 44435189, 2025-07-01) +- One third-party review title claims a "$16 Cloud" plan, which conflicts with the official $20 Plus price. Treat it as stale or unreliable. — [a8gent.com](https://a8gent.com/platforms/activepieces) + +### Inferences +- "Team ~$200/mo" is confirmed: $200/mo flat for 25 users. That is the cheapest tier with SSO and roles. Audit logs, git sync/releases, secret managers, SCIM, and custom roles need Ultimate or Enterprise (custom quote). +- For self-hosters this is a three-tier picture: CE (MIT, free, minimal governance), EE with Plus/Team bought in-app, and EE with a custom license key. I did not verify exactly how credit and user caps apply self-hosted on EE. + +### Gaps +- Self-hosted price for Ultimate/Enterprise (not published). +- Whether self-hosted Plus/Team charge the same $20/$200, and whether the credit meter applies to self-hosted runs or only to AI calls. Docs say only that plans are "available self-hosted". + +## 3. Feature gating (SSO, RBAC, users, projects, audit logs, log streaming, retention, environments/releases, git sync, secrets, versioning, workers/HA) + +### Takeaway +Per the pricing page and the enterprise-license docs, the Community Edition is the core alone: SSO, project/standard/custom roles, SCIM, audit logs, secret managers, releases/git sync, event streaming, global connections, dedicated workers, embedding, custom branding, and private piece management are paid features. Retention is configurable for free through documented env vars. Horizontal worker scaling and HA are documented as general architecture, with only dedicated workers / worker groups listed as paid. + +### Cited Findings +- **License-key features (docs)**: "Standard and custom roles", "SCIM user provisioning", "Projects and multi-tenancy", "Embeddable builder and JavaScript SDK", and "Custom branding and domains" are listed as features unlocked by a license key. — [docs: enterprise license](https://www.activepieces.com/docs/install/configure-operate/enterprise-license) +- **SSO**: Cloud: Team and above. The docs have a dedicated SSO guide (SAML and Google/federated sign-in). — [pricing](https://www.activepieces.com/pricing), [docs: SSO guide](https://www.activepieces.com/docs/admin-guide/guides/sso) +- **User counts**: cloud Free/Plus allow up to 5 users, Team 25 included, Ultimate unlimited. — [pricing](https://www.activepieces.com/pricing) +- **Audit logs**: Ultimate/Enterprise only. Retention is set by `AP_AUDIT_LOG_RETENTION_DAYS` (30 to 3650, empty = forever). — [docs: environment variables](https://www.activepieces.com/docs/install/reference/environment-variables), [pricing](https://www.activepieces.com/pricing) +- **Log/event streaming**: "Event streaming" is listed under Ultimate. — [pricing](https://www.activepieces.com/pricing) +- **Execution data retention (not gated)**: `AP_EXECUTION_DATA_RETENTION_DAYS` (default `30`) covers "execution data, logs, and events", and should be strictly greater than `AP_PAUSED_FLOW_TIMEOUT_DAYS` (default 30). Cloud is fixed at 30 days. Admins can shorten retention per project. Other limits: `AP_MAX_FLOW_RUN_LOG_SIZE_MB` 50, `AP_FLOW_TIMEOUT_SECONDS` 600, `AP_MAX_FILE_SIZE_MB` 25, `AP_MAX_RECORDS_PER_TABLE` 10000. — [docs: environment variables](https://www.activepieces.com/docs/install/reference/environment-variables), [docs: limits](https://www.activepieces.com/docs/install/reference/limits) +- **Multiple environments / Project Releases / Git Sync**: "Project Releases allow you to sync flows, connections, and tables between different projects … develop in one environment and deploy to another." Releases come from Git, from another project, or from a rollback. The feature is enabled under project Settings → Environments. Pricing: "releases and Git Sync" is Ultimate only. — [docs: project releases](https://www.activepieces.com/docs/admin-guide/guides/project-releases), [pricing](https://www.activepieces.com/pricing) +- **External secrets**: the docs cover AWS Secrets Manager, CyberArk Conjur, HashiCorp Vault, and 1Password. Ultimate/Enterprise. — [docs: secret managers](https://www.activepieces.com/docs/admin-guide/guides/secret-managers), [pricing](https://www.activepieces.com/pricing) +- **Flow versioning**: one third-party review claims "no native version control for flows". — [syncgtm review via search](https://syncgtm.com/blog/activepieces-review). Not verified against official docs; see Gaps. +- **Workers / HA / scaling**: "Workers are stateless … scale horizontally: add replicas behind any orchestrator." Crashed worker jobs are requeued by BullMQ and "durable replay skips every completed step." `AP_CONTAINER_TYPE` = `APP` | `WORKER` | `WORKER_AND_APP`. Redis Sentinel is supported. Only dedicated workers are gated ("Dedicated workers" on Ultimate). — [docs: workers](https://www.activepieces.com/docs/install/architecture/workers), [docs: environment variables](https://www.activepieces.com/docs/install/reference/environment-variables), [pricing](https://www.activepieces.com/pricing) +- **Other gated items**: global connections (Team+), piece management / private pieces, template management, custom branding/domains, embedding SDK. — [docs: enterprise license](https://www.activepieces.com/docs/install/configure-operate/enterprise-license), [pricing](https://www.activepieces.com/pricing) + +### Inferences +- Since "Projects and multi-tenancy" and roles are license-key features, CE is unlikely to offer real shared-workspace RBAC for a team. Whether CE allows multiple user accounts at all, and how they are isolated, should be checked in a running instance. +- The n8n features people most often miss (SSO, environments/git, external secrets, log streaming, audit logs) map to Activepieces tiers like this: SSO at Team ($200/mo). Git/environments, secrets, and audit logs at Ultimate (custom). Arguably stricter than n8n's gating for git and environments. +- Unlike n8n Community, CE has no documented gating on retention or worker scaling. + +### Gaps +- I did not verify in a running instance which multi-user and invitation features CE's UI exposes. +- Whether flow version history is available (and in which edition) was not confirmed from official docs. + +## 4. Product model (builder, pieces, triggers, code, AI/agents/MCP, embedding) + +### Takeaway +A linear, step-based visual builder that is closer to Zapier than to n8n's free-form node graph. Integrations ("pieces") are TypeScript npm packages; third-party reviews quote 300+ pieces. It includes code steps, subflows, approvals/waitpoints, tables, MCP support, and AI agents. Embedding/white-label is a separate Embed plan (from $36k/yr). + +### Cited Findings +- Third-party reviews quote "300+" or "~330+" pieces. — [agntable](https://www.agntable.com/blog/activepieces-vs-n8n), [syncgtm](https://syncgtm.com/blog/activepieces-review). Counts may be stale or counted differently. +- The vendor positions n8n as node-based for technical users and Activepieces as "step-based builder" built for usability and speed. — [activepieces.com blog](https://www.activepieces.com/blog/activepieces-vs-n8n) +- HN Apr 2025: "Show HN: Largest Open Source MCP Repo (280)". — [HN Algolia](https://hn.algolia.com/api/v1/search?query=activepieces&tags=story) +- Durable pause/resume ("Waitpoints") was launched 2026-04-01. — [everydev.ai](https://www.everydev.ai/tools/activepieces); [docs: waitpoints](https://www.activepieces.com/docs/install/architecture/waitpoints) +- Code steps run sandboxed per `AP_EXECUTION_MODE` (`UNSANDBOXED` default in CE; `SANDBOX_CODE_ONLY` is required with `AP_EDITION=ee`). — [docs: environment variables](https://www.activepieces.com/docs/install/reference/environment-variables), [docs: docker-compose](https://www.activepieces.com/docs/install/options/docker-compose) +- Embedding: "Embeddable builder and JavaScript SDK", "Custom branding and domains" are paid. The Embed plan is "From $36k/year". — [docs: enterprise license](https://www.activepieces.com/docs/install/configure-operate/enterprise-license), [pricing](https://www.activepieces.com/pricing) +- Pricing lists Flows, Agents, Tables, MCPs, and "chat to automation" on every cloud tier. — [pricing](https://www.activepieces.com/pricing) + +### Inferences +- Pieces are written in TypeScript and published as npm packages, so custom integrations are much easier to build than n8n custom nodes. Private pieces at org level are a paid feature. +- Which AI features (standalone agents, AI chat, in-flow agent steps) are available in self-hosted CE was not confirmed from docs. + +### Gaps +- Exact trigger model (polling vs webhook) per piece was not researched in depth. Schedule, webhook and manual triggers are available. +- AI feature availability per edition in self-hosted deployments. + +## 5. Tech stack & ops + +### Takeaway +TypeScript/Node.js, with a Redis-backed BullMQ queue. The recommended self-host runs PostgreSQL + Redis (+ optional S3). There is also a single-container "hobby" mode on embedded PGLite with in-memory Redis. Docker Compose and Helm are both official. Sizing is documented: workers at 0.5 vCPU / 1 GB each with concurrency 1, and one app per ten workers. + +### Cited Findings +- Recommended install: `curl -fsSL https://get.activepieces.com | sh` (Docker Compose v2, PostgreSQL + Redis). The Helm chart is "only if you already run a cluster". — [docs: install overview](https://www.activepieces.com/docs/install/overview) +- Hobby: a single container with `AP_DB_TYPE=PGLITE`, `AP_REDIS_TYPE=MEMORY`. It "cannot scale, cannot move to Enterprise, and moving off it means starting over." SQLITE3 is deprecated and auto-migrated to PGLITE. — [docs: docker](https://www.activepieces.com/docs/install/options/docker), [docs: environment variables](https://www.activepieces.com/docs/install/reference/environment-variables) +- Redis backs the BullMQ queue, in modes MEMORY, STANDALONE, or SENTINEL. — [docs: environment variables](https://www.activepieces.com/docs/install/reference/environment-variables) +- Production sizing: Worker 0.5 vCPU / 1 GB (concurrency 1, one per concurrent flow). App 1 vCPU / 1 GB (one per ten workers). Postgres 2 vCPU / 4 GB managed. Redis 1 vCPU / 1 GB. Example: "At 50 concurrent flows: 50 workers (25 vCPU / 50 GB) + 5 apps". Benchmark: 777 req/s with 160 workers, and Postgres becomes the bottleneck past about 80 workers. The legacy default concurrency of 5 needs about 2.5 vCPU / 5 GB per worker. — [docs: production setup](https://www.activepieces.com/docs/install/configure-operate/production-setup) +- A vendor-neutral-ish comparison counts 3 containers (app + PostgreSQL + Redis) for Activepieces vs 2 for n8n. — [agntable](https://www.agntable.com/blog/activepieces-vs-n8n) + +### Inferences +- A small team can run it on a single 2 to 4 GB VM with the combined `WORKER_AND_APP` container. Production at scale is heavier per concurrent flow than n8n queue mode, because the recommended model is one flow per worker. + +### Gaps +- I found no measured idle RAM figure for a minimal Compose stack. + +## 6. Community health + +### Takeaway +Very active. About 25.3k stars, about 4.4k forks, 357 listed contributors, and near-daily releases and hotfixes (v0.92.3 as of Oct 2026, still pre-1.0). It is a YC S22 company. Published funding is small and sources conflict. + +### Cited Findings +- GitHub API (2026-10-29): 25,283 stars, 4,405 forks, created 2022-12-03, last push 2026-10-29. — [GitHub](https://github.com/activepieces/activepieces) +- Contributors endpoint paginates to 357 (per_page=1). — [GitHub contributors API](https://api.github.com/repos/activepieces/activepieces/contributors) +- Releases: 0.86.3 (2026-07-17), 0.87.0 (08-06), 0.88.0 (08-12), 0.91.0 (09-14), 0.92.0 (09-24), 0.92.3 (10-12). Hotfixes on several branches between Oct 23 and 29, 2026. Versioning is still 0.x. — [GitHub releases](https://github.com/activepieces/activepieces/releases) +- Launch HN (YC S22), 2023-02-09: 231 points, 62 comments. — [HN 34723989](https://news.ycombinator.com/item?id=34723989) +- Funding: YC S22. Amounts conflict: $1.6M seed in Mar 2023 per VCBacked, a $0.5M convertible note per CB Insights, $6.4M total per startups.fm. No 2026 round found. — [vcbacked](https://www.vcbacked.co/company/activepieces), [cbinsights](https://www.cbinsights.com/company/activepieces), [startups.fm](https://startups.fm/startups/activepieces) + +### Inferences +- About 1 to 2 minor versions per month, plus hotfix backports to several older lines, suggests a busy cadence but also frequent upgrades. Pre-1.0 versioning plus a docs page titled "breaking-changes-unreleased" points to ongoing churn. + +### Gaps +- Verified funding total, headcount, and revenue. + +## 7. Migration from n8n + +### Takeaway +There is no documented n8n importer. Migration means a manual rebuild: map n8n nodes to pieces, rewrite Code nodes in TS/JS code steps, and recreate credentials as connections. + +### Cited Findings +- No n8n import tool is documented. Activepieces imports its own flow JSON ("Import Flow"). Credentials must be reconnected. — [neura.market listing](https://neura.market/workflow/weekly-industry-updates) +- A community forum user coming from n8n asked about export/import equivalents. — [community.activepieces.com](https://community.activepieces.com/t/flow-export-import-function/1904) +- The vendor n8n comparison gives no migration advice or tool. — [activepieces.com blog](https://www.activepieces.com/blog/activepieces-vs-n8n) + +### Inferences +- Concept mapping: n8n workflow → flow. Node → step/piece action. Trigger node → trigger (webhook/schedule/piece trigger). Code node → Code step (TS/JS). Execute Workflow → Subflows piece. Wait → Delay/approval/waitpoints. Credentials → Connections (global connections are paid). Projects → Projects (team projects are paid). n8n environments/git → Project Releases/Git Sync (Ultimate). +- Effort: moderate to high for complex n8n graphs (branching, merges, item-list semantics), because Activepieces flows are linear with branches and loops rather than arbitrary DAGs with n8n's per-item execution model. Simple Zapier-style flows rebuild quickly. + +### Gaps +- No first-hand migration case studies found. + +## 8. Known limitations / criticisms + +### Takeaway +The main criticisms: the enterprise features most teams need (SSO from $200/mo, git/environments/audit/secrets only on custom Ultimate) are gated, contrary to the "fully MIT" messaging. The integration catalog is smaller than Zapier's, the linear builder is less flexible than n8n, docs for advanced self-hosting are sparse, and fast pre-1.0 churn means frequent upgrades. Reddit-specific threads did not show up in searches, so most criticisms come from review blogs of uneven quality. + +### Cited Findings +- Reviews disagree on what is paywalled (SSO/SAML, audit logs, branding, RBAC, white-label). One notes that having the source does not grant rights to the commercial modules. — [ohaiknow](https://ohaiknow.com/reviews/activepieces/), [opsily (managed-n8n vendor, biased)](https://opsily.com/hosting/n8n/activepieces-self-hosted-limitations), [baeseokjae](https://baeseokjae.github.io/posts/activepieces-review-2026/) +- Single-source claims: no sub-flow architecture, more manual error handling, a loop step failing silently on empty arrays, no native flow version control. — [syncgtm](https://syncgtm.com/blog/activepieces-review). The sub-flow claim conflicts with the product's documented Subflows piece; the versioning claim is unverified. +- Smaller catalog (300+ vs Zapier's 7,000+), and some pieces have few triggers/actions. — [syncgtm](https://syncgtm.com/blog/activepieces-review), [workflowautomation.net](https://workflowautomation.net/reviews/activepieces) +- Sparse or outdated docs for Kubernetes, multi-tenant, and enterprise SSO. Community-only support (Discord/GitHub) on free. No SOC 2 / HIPAA BAA for self-hosted. — [review roundup via search: noviqip](https://noviqip.com/blogs/guides/activepieces-review-2026), [digioffly](https://digioffly.com/activepieces-review/) +- n8n is seen as more flexible and powerful for code-heavy users, while G2 reviewers praise Activepieces' easy setup. — [G2 compare](https://www.g2.com/compare/activepieces-vs-n8n), [agntable](https://www.agntable.com/blog/activepieces-vs-n8n) +- Default `AP_EXECUTION_MODE=UNSANDBOXED` in CE. The docs call sandboxing "the most important security decision for multi-tenant deployments". — [docs: workers](https://www.activepieces.com/docs/install/architecture/workers), [docs: environment variables](https://www.activepieces.com/docs/install/reference/environment-variables) +- The docs themselves warn that the default `AP_WORKER_CONCURRENCY=5` "widens the OOM blast radius", and that `AP_PREWARM_CACHE_ON_STARTUP` can OOM small workers. — [docs: workers](https://www.activepieces.com/docs/install/architecture/workers), [docs: environment variables](https://www.activepieces.com/docs/install/reference/environment-variables) + +### Inferences +- For an n8n refugee who wants self-hosted SSO + git + environments for free, Activepieces CE does not solve the gating problem. It is arguably stricter than n8n on git and environments. Its advantage is a truly MIT core (no SUL restrictions on commercial or embedded use of the core), with unrestricted retention and scaling. + +### Gaps +- No usable r/selfhosted or r/n8n threads turned up in searches. The HN Launch thread (2023) comments were not read in detail. diff --git a/docs/research/notes/kestra.md b/docs/research/notes/kestra.md new file mode 100644 index 0000000..de548e1 --- /dev/null +++ b/docs/research/notes/kestra.md @@ -0,0 +1,170 @@ +> Ported from earlier research (2026-10-29) and sanitized for clean-room use: source-code-derived details removed. Not legal advice. + +# Kestra as a self-hosted n8n alternative (as of late October 2026) + +Research date: 2026-10-29. The current major version is Kestra 2.0, released 8 Sep 2026; the latest patch is v2.0.8 (27 Oct). Anything that describes 1.x is marked as older. + +## 1. License (open-source core, proprietary parts, license changes) + +### Takeaway +The open-source core (kestra-io/kestra) is Apache-2.0. Enterprise features are closed-source proprietary code (separate Enterprise plugins) sold under a commercial subscription. I found no evidence of a license change in 2023-2026, unlike n8n's Sustainable Use License. + +### Cited Findings +- The GitHub repo license is Apache-2.0 (30.1k stars, 3.5k forks, about 13,446 commits on the `develop` branch) — [GitHub kestra-io/kestra](https://github.com/kestra-io/kestra) +- The open-source edition is free under Apache 2.0. Enterprise Edition is an annual per-instance subscription with custom pricing — [automationatlas.io pricing explainer](https://automationatlas.io/answers/kestra-pricing-explained-2026/); [kestra.io/pricing](https://kestra.io/pricing) +- EE features ship as separate Enterprise plugins (for example an Enterprise Git plugin). In 2.0, Git dashboard tasks (`SyncDashboards`/`PushDashboards`) moved from the OSS Git plugin to the EE Git plugin, and dashboards moved to EE — [Kestra 2.0 migration guide](https://kestra.io/docs/migration-guide/v2.0.0); [Kestra 2.0 release blog](https://kestra.io/blogs/release-2-0) + +### Inferences +- The model is open-core: an Apache-2.0 core plus proprietary EE add-ons. Nothing I found suggests a "source-available" middle tier like n8n's source-available enterprise code. The EE code does not appear in the public repo. +- Moving dashboards to EE in 2.0 means features can migrate from OSS to paid between majors. That is a mild "open-core creep" risk to keep in mind, even though the license itself has not changed. + +### Gaps +- I did not find an official statement ruling out past license changes. The "no change" conclusion rests on the repo being Apache-2.0 today and no search results reporting a change. +- I did not verify the exact license text of the EE plugins (EULA or commercial terms). + +## 2. Free vs paid editions and pricing + +### Takeaway +There are three editions. Open Source is free. Enterprise Edition is self-hosted, priced per instance, with unlimited flows, tasks and executions and no public price. Kestra Cloud is managed and usage-based, with no public price; it was in early or request access through at least mid-2026. + +### Cited Findings +- Pricing page: Open Source costs 0 USD. Enterprise is "Per instance model, unlimited flows/tasks/executions" (contact sales). Cloud is "pay only for what you use", with no fixed price shown — [kestra.io/pricing](https://kestra.io/pricing) +- As of July 2026, Kestra Cloud was described as early access with usage-based pricing and no published dollar prices. Another listing (verified March 2026) says "Contact sales". The sources conflict on access mode — [automationatlas.io](https://automationatlas.io/answers/kestra-pricing-explained-2026/); [toolradar](https://toolradar.com/tools/kestra/pricing) +- The Series A funds (March 2026) were earmarked for Kestra 2.0, the Kestra Cloud rollout, and North America and Europe expansion — [raising.fi](https://raising.fi/news/kestra-series-a-march-2026); [Axios Pro](https://axios.com/pro/enterprise-software-deals/2026/03/31/workflow-orchestration-kestra-enterprise) + +### Inferences +- EE pricing is per instance rather than per user or per execution, so the cost doesn't grow with user count. Without public numbers, it is likely aimed at mid-market and enterprise budgets (inference only). + +### Gaps +- No public price exists for EE or Cloud. No source reported a small-team or startup tier. + +## 3. Feature gating (the features the user cares about) + +### Takeaway +Almost every governance feature on the user's list is EE/Cloud-only: SSO, LDAP, SCIM, RBAC, multiple users, multi-tenancy, audit logs, log shippers, external secrets managers, worker groups, and environment promotion. OSS keeps Git sync tasks, namespaces, execution purge tasks, flow revisions, and the ability to run as a distributed cluster. OSS authentication is a single shared Basic Auth account. + +### Cited Findings (gating table; OSS = open source, EE = Enterprise and Cloud) +- **SSO (OIDC), LDAP, SCIM:** EE only. The docs say SSO is "via OpenID Connect (OIDC) or LDAP". SCIM syncs users and groups. 2.0 adds an LDAP group-sync-only mode (EE) — [docs: OSS vs paid](https://kestra.io/docs/oss-vs-paid); [pricing](https://kestra.io/pricing); [2.0 blog](https://kestra.io/blogs/release-2-0) + - SAML: these pages mention only OIDC and LDAP. A third-party listing mentions "SSO / SAML" for Cloud — [toolradar](https://toolradar.com/tools/kestra/pricing). Treat SAML support as unverified. +- **Multi-user and number of users:** OSS has "one shared Basic Authentication account". EE has individual accounts through invitations, plus SCIM — [docs: OSS vs paid](https://kestra.io/docs/oss-vs-paid) +- **RBAC:** EE only. In 2.0, RBAC moved from CRUD to 159 per-action permissions with five managed role presets (Viewer, Launcher, Editor, Developer, Admin), scoped per namespace and assignable to users, groups and service accounts — [2.0 blog](https://kestra.io/blogs/release-2-0); [pricing](https://kestra.io/pricing) +- **Namespaces / tenants / teams:** Namespaces are a core concept and exist in OSS. Multi-tenancy, with isolated tenants and per-tenant secrets and storage, is EE. Per-namespace governance of secrets, variables and files is EE — [docs: OSS vs paid](https://kestra.io/docs/oss-vs-paid); [pricing](https://kestra.io/pricing) +- **Audit logs:** EE only ("Record every action by every user on every resource"). In 2.0, the Audit Log Shipper can send Syslog CEF events over TCP, UDP or TLS — [pricing](https://kestra.io/pricing); [2.0 blog](https://kestra.io/blogs/release-2-0) +- **Log streaming / log shippers:** EE only. The Log Shipper sends logs to Datadog, Splunk, Elasticsearch and others, plus a CEF syslog exporter in 2.0. The External Log Data Store (route logs to a separate JDBC DB or Elasticsearch) is also EE — [pricing](https://kestra.io/pricing); [docs: OSS vs paid](https://kestra.io/docs/oss-vs-paid); [2.0 blog](https://kestra.io/blogs/release-2-0) +- **Execution data retention and purge:** OSS has core tasks `PurgeExecutions`, `PurgeLogs` and `PurgeKV`. You schedule them as flows with a date cutoff such as `endDate: now() | dateAdd(-1,'MONTHS')`, filter by state, and select which data to delete. They replace the legacy `storage.Purge`. `PurgeStorage` (orphaned files, dry run by default) arrived in 2.0 for OSS, EE and Cloud. There is no built-in retention setting; retention is done by flows — [admin guide: purge](https://kestra.io/docs/administrator-guide/purge); [PurgeExecutions plugin](https://kestra.io/plugins/core/execution/io.kestra.plugin.core.execution.purgeexecutions); [best practices: purging](https://kestra.io/docs/best-practices/purging-data); [2.0 blog](https://kestra.io/blogs/release-2-0) + - 2.0 also adds Quotas, which limit executions per flow, namespace or tenant in a time window. The edition was not stated — [2.0 blog](https://kestra.io/blogs/release-2-0) +- **Multiple environments:** EE-native. **Promote** (new in 2.0, EE/Cloud) moves flows between environments with diffs, protected-target confirmation, drift status and audit history, and needs no Git. In OSS you build environments yourself: separate instances, or namespace naming (e.g. `dev.*`, `prod.*`) plus Git sync — [2.0 blog](https://kestra.io/blogs/release-2-0); [docs: git](https://kestra.io/docs/version-control-cicd/git) +- **Git version control:** OSS includes `SyncFlows`, `PushFlows`, `SyncNamespaceFiles`, `PushNamespaceFiles`, `Clone`, and `TenantSync`/`NamespaceSync` (bidirectional via `sourceOfTruth`). These run as Kestra flows triggered by schedule or webhook. EE-only: Promote, `PushBlueprints`/`SyncBlueprints`, `SyncApps`, `SyncUnitTests`, `SyncDashboards`, and auto-creating namespaces. The pricing page lists "Git integration and versioning" in both editions — [docs: git](https://kestra.io/docs/version-control-cicd/git); [pricing](https://kestra.io/pricing) + - Caveat: the docs page doesn't explicitly label the first four as OSS. The OSS status is an inference from the missing EE label, consistent with the pricing page. +- **External secrets managers:** EE/Cloud only ("Available on: Enterprise Edition and Cloud"). Supported: AWS Secrets Manager, AWS SSM Parameter Store, Azure Key Vault, Google Secret Manager, HashiCorp Vault, CyberArk, Doppler, 1Password, BeyondTrust, Delinea, and Bitwarden. Read-only mode is supported and can be set globally, per tenant or per namespace. In OSS, secrets are supplied as (base64) environment variables — [docs: secrets manager](https://kestra.io/docs/enterprise/governance/secrets-manager); [docs: OSS vs paid](https://kestra.io/docs/oss-vs-paid) +- **Workflow versioning and history:** Flows have revisions in the core product. 2.0 adds **draft revisions**: drafts never run, and triggers use the last published revision (edition not stated). Plugin versioning (pinning plugin versions per task, flow, namespace or instance) is EE, introduced in 0.22 (older) — [2.0 blog](https://kestra.io/blogs/release-2-0); [0.22 release blog](https://kestra.io/blogs/release-0-22); [docs: OSS vs paid](https://kestra.io/docs/oss-vs-paid) +- **HA, workers and scaling:** OSS can run as a standalone server or a distributed cluster with separate components. EE adds Worker Groups (tag-based routing with `workerSelector.tags` and capacity reservation), tenant-restricted capacity, Maintenance Mode, and cloud VM task runners (EC2, Azure VM, GCE). In 2.0 every worker connects outbound over gRPC and needs no DB access — [docs: OSS vs paid](https://kestra.io/docs/oss-vs-paid); [2.0 blog](https://kestra.io/blogs/release-2-0) +- **Other EE-only extras:** Apps (forms, approvals and dashboards on top of flows), Policies (namespace rules that replace `pluginDefaults`), Cases (incident management), Reusable Inputs, asset locking, and the agentic AI Copilot — [pricing](https://kestra.io/pricing); [2.0 blog](https://kestra.io/blogs/release-2-0) + +### Inferences +- For a multi-user team that needs any access control, OSS Kestra is effectively single-tenant and single-credential, so you would need EE. Even n8n's free Community edition has per-user accounts, so on user management OSS Kestra is more restrictive than n8n Community. +- OSS Kestra is stronger than n8n Community on Git sync and execution purge, which are free in Kestra, and on horizontal scaling. + +### Gaps +- I could not confirm whether OSS flow revision history is fully visible and restorable in the UI in 2.0, though it was in 1.x from my background knowledge (unverified here). +- SAML support was not confirmed from official docs. +- The edition gating of Quotas and draft revisions was not stated. + +## 4. Product model (definition, editor, users, triggers, integrations, AI) + +### Takeaway +Kestra is a declarative, YAML-first, event-driven orchestration platform. Its roots and audience are data engineering and platform teams, and it now also markets for infrastructure and AI workflows. A no-code form editor, the YAML editor and the AI Copilot all edit the same flow. There is no free-form node canvas like n8n's; the topology view is mostly for visualization. + +### Cited Findings +- The project describes itself as "Orchestrate everything, everywhere": an event-driven platform for data, AI and infrastructure workflows, with flows declared in YAML. The YAML editor, no-code editor and AI Copilot all edit the same flow — [GitHub](https://github.com/kestra-io/kestra) +- In 2.0 the no-code editor is form-based with a contextual data panel, kept in sync with YAML and Copilot (OSS, EE, Cloud) — [2.0 blog](https://kestra.io/blogs/release-2-0) +- Triggers: schedules, events and webhooks, plus flow triggers (`dependsOn` with a window) and a single Pebble `when` expression in 2.0 that replaces `conditions` — [GitHub](https://github.com/kestra-io/kestra); [2.0 blog](https://kestra.io/blogs/release-2-0) +- Integrations: the plugins page claims "2,400+ plugins". A March 2026 press article said "more than 1,200 plugins". The jump probably reflects counting method or growth — [kestra.io/plugins](https://kestra.io/plugins); [The Next Web](https://thenextweb.com/news/orchestration-platform-kestra-raises-25m) +- AI: the MCP Server and MCP Tool Trigger expose flows as tools to Claude Desktop, Claude Code, Cursor and Codex (OSS, EE, Cloud). Additional MCP servers are EE. AI Agent tasks gain guardrails and metrics. The AI Copilot with Ask, Edit and Plan modes and memory is EE/Cloud (on any LLM). The pricing page lists an OSS "AI Copilot (Gemini)" and AI Agents — [2.0 blog](https://kestra.io/blogs/release-2-0); [pricing](https://kestra.io/pricing) +- Positioning versus n8n: Kestra is for engineering teams that want declarative, infrastructure-as-code orchestration. Business and app-centric automation is "usually easier in n8n" because of its app canvas — [openalternative.co](https://openalternative.co/compare/kestra/vs/n8n); [ZoomInfo comparison](https://pipeline.zoominfo.com/sales/kestra-vs-n8n) +- Other: unit tests for flows (in 2.0, `expectedState` assertions), the `Loop` task that replaces ForEach and ForEachItem, a VS Code extension, and OpenTelemetry trace propagation — [2.0 blog](https://kestra.io/blogs/release-2-0) + +### Inferences +- Kestra's plugin catalog leans toward data, cloud and infrastructure (databases, warehouses, dbt, cloud services, VMware/Nutanix). It has comparatively fewer SaaS-app connectors (CRM, marketing) than n8n. This comes from the plugin positioning and the infrastructure plugin lists, not from a full catalog audit. +- The 2,400+ figure likely counts individual tasks and triggers rather than distinct services, so it is not directly comparable to n8n's node count. + +### Gaps +- I did not get a count of distinct SaaS services or apps. + +## 5. Tech stack and operations + +### Takeaway +Kestra is Java (JVM, Gradle, Micronaut-based from background knowledge) with a Vue.js UI. The minimal production setup is one PostgreSQL instance as both queue and repository, plus local or S3-compatible storage. Kafka, Redis or AMQP can act as the queue for scale. 2.0 removed the Kafka Streams engine, and Elasticsearch is now an EE external log store. It is deployed with Docker Compose or Helm. + +### Cited Findings +- The repo is tagged `java` and uses Gradle — [GitHub](https://github.com/kestra-io/kestra) +- 2.0 architecture: the control plane (Executor, Worker Controller, Scheduler, Webserver, Indexer) is separate from the data plane (Workers). Workers open one outbound gRPC stream with optional TLS, mTLS or JWT and need no database connection. Queue and repository are decoupled. Recommended start: a single PostgreSQL instance as queue and repository, with the option to move the queue to Kafka, Redis or AMQP. The Kafka Streams engine was removed — [2.0 blog](https://kestra.io/blogs/release-2-0) +- Elasticsearch and JDBC (H2, PostgreSQL, MySQL) can serve as the EE External Log Data Store — [2.0 blog](https://kestra.io/blogs/release-2-0) +- The official Docker Compose runs Kestra plus `postgres` with `repository: type: postgres` and `queue: type: postgres`, local storage at `/app/storage`, and an S3 / SeaweedFS (minio type) option. It starts a standalone server with "all architectural components running in one JVM". The docs give no CPU or RAM minimums — [docs: docker compose](https://kestra.io/docs/installation/docker-compose) +- The Helm chart (EE) exposes gRPC port 50051 by default and adds a controller deployment in 2.0 — [migration guide](https://kestra.io/docs/migration-guide/v2.0.0) +- `*-slim` images ship with no plugins. `KESTRA_PLUGINS_AUTO_INSTALL_ENABLED=true` pulls referenced plugins from Maven Central on first use — [2.0 blog](https://kestra.io/blogs/release-2-0) +- Footprint criticism: "Java-based engine has heavier baseline resource footprint than lightweight Python schedulers" (third-party review) — [aitoolsatlas pros/cons](https://aitoolsatlas.ai/tools/kestra/pros-cons) +- Upgrade burden: 2.0 requires being on the latest 1.3.x first. OSS migrations run automatically, while EE needs manual `kestra migrate plan/run`. The BasicAuth password rehash can't be rolled back. There are many breaking DSL changes (ForEach removed, `conditions` replaced by `when`, `pluginDefaults` removed, `json()` replaced by `fromJson()`, Parallel/Dag fail-fast default) — [migration guide](https://kestra.io/docs/migration-guide/v2.0.0) + +### Inferences +- For small self-hosting, a Kestra plus Postgres compose stack is about as simple as n8n plus Postgres. The JVM probably means a higher idle RAM baseline (likely 1-2 GB+, unverified) than n8n's Node.js process. +- Before 2.0 (older info), large deployments used the EE Kafka plus Elasticsearch backend. 2.0 simplifies this considerably. + +### Gaps +- No official minimum CPU or RAM figures were found. +- The MySQL repository status in 2.0 OSS was not confirmed; the docs only mention it for the log store and secrets backend. + +## 6. Community health + +### Takeaway +Community health is strong and well funded. The repo has about 30.1k GitHub stars, weekly patch releases on two maintained lines (2.0.x LTS and 1.3.x), and a $25M Series A (Mar 2026, about $36M raised in total). Its community is much smaller than n8n's. + +### Cited Findings +- 30.1k stars, 3.5k forks, 169 watchers, about 13.4k commits. The contributor count was not shown on the page — [GitHub](https://github.com/kestra-io/kestra) +- Release cadence: roughly weekly. v2.0.4 (29 Sep), v2.0.5 (5 Oct), v2.0.6 (13 Oct), v2.0.7 (20 Oct), v2.0.8 (27 Oct), each shipped alongside a 1.3.x patch (v1.3.41 to v1.3.45) — [GitHub releases](https://github.com/kestra-io/kestra/releases) +- 2.0 is an LTS release with one year of backported fixes. Launch post dated 8 Sep 2026 — [2.0 blog](https://kestra.io/blogs/release-2-0); [web search summary of Anna Geller's LinkedIn](https://de.linkedin.com/in/geller-anna) +- Funding: $25M Series A on 31 Mar 2026, led by RTP Global with Alven, ISAI and Axeleo, about $36M total. Earlier: an $8M seed led by Alven (Sep 2024). Tech.eu lists €22M / €29M total, which is a currency or conversion discrepancy — [The Next Web](https://thenextweb.com/news/orchestration-platform-kestra-raises-25m); [Alven](https://alven.co/kestra-raises-8m-to-lead-the-future-of-orchestration-for-business-critical-workflows); [tech.eu](https://funding.tech.eu/companies/B53F386F-689A-4978-B511-29985B65967F) +- Traction claims (vendor): enterprise revenue up 25x in 18 months, over 2B workflows executed in 2025, and Apple engineers among its users — [The Next Web](https://thenextweb.com/news/orchestration-platform-kestra-raises-25m); [Pulse 2.0](https://pulse2.com/kestra-25-million-raised-for-open-source-orchestration-platform-expansion/amp/) +- Older snapshot comparison: n8n had about 184.8k stars versus Kestra's about 26.7k — [openalternative.co](https://openalternative.co/compare/kestra/vs/n8n) +- The company is French; the CTO built the precursor at the game publisher Ankama for distributed cron jobs — [Pulse 2.0 interview](https://pulse2.com/kestra-profile-ludovic-dehon-interview/) + +### Inferences +- Funding and LTS commitments suggest low abandonment risk. The commercial incentive to push governance into EE will remain. + +### Gaps +- The exact contributor count is unknown; the GitHub page didn't render it. + +## 7. Migration from n8n + +### Takeaway +There is no n8n importer. Kestra publishes a migration guide for Pipedream but none for n8n. n8n workflows would need a manual rewrite into YAML flows. Code nodes port to script tasks fairly directly, while the many SaaS nodes need equivalent plugins or HTTP Request tasks. + +### Cited Findings +- No n8n-specific migration path was found. Kestra's Pipedream migration page says "Node.js, Python and Bash steps copy into script tasks; what changes is how they read their input and return their results" — [Kestra: migrate from Pipedream](https://kestra.io/resources/migration/pipedream) +- Comparison sites contrast n8n's visual canvas for app-centric automation with Kestra's declarative, engineering-oriented model — [openalternative.co](https://openalternative.co/compare/kestra/vs/n8n); [ZoomInfo](https://pipeline.zoominfo.com/sales/kestra-vs-n8n) + +### Inferences +- Concept mapping: n8n workflow maps to a Kestra flow (in a namespace), n8n trigger node to a trigger (Schedule, Webhook, polling or realtime trigger), n8n node to a task, n8n credentials to secrets, n8n expressions to Pebble expressions, and n8n sub-workflow to a Subflow task. The mapping is conceptually clean, but data passing differs: Kestra uses explicit outputs and `{{ outputs.task.x }}` instead of item arrays flowing between nodes. +- Effort: moderate to high for SaaS-heavy n8n workflows, lower for code and API-heavy ones. An LLM could help convert n8n JSON to Kestra YAML, but that is untested. + +### Gaps +- No community-built n8n-to-Kestra converter was found. + +## 8. Known limitations and criticisms + +### Takeaway +Independent criticism is thin; I found no substantive Reddit or HN threads. The recurring points are: governance is paywalled with an unpublished EE price, the JVM has a heavier footprint, the plugin ecosystem is smaller than Airflow's, YAML has a learning curve, and the 1.x to 2.0 upgrade breaks things. For n8n users specifically, the bigger issues are the lack of a canvas-style editor and fewer business-SaaS connectors. + +### Cited Findings +- Third-party pros and cons list heavier Java footprint, unpublished enterprise pricing that "requires a sales conversation for RBAC/audit features", a smaller ecosystem than Airflow (some providers need custom plugins), and a learning curve for Airflow users. Verdict 5.5/10 — [aitoolsatlas pros/cons](https://aitoolsatlas.ai/tools/kestra/pros-cons) +- Positive community themes (secondhand, reportedly from Reddit): UI plus YAML lowers the barrier for non-Python authors and is simpler than Airflow or Prefect. Formal review-platform evidence is thin — [aitoolsatlas](https://aitoolsatlas.ai/tools/kestra/pros-cons); other favorable review (7.8/10): [makerstack](https://makerstack.co/reviews/kestra-review/) +- Kestra's own rebuttal of YAML criticisms (vendor marketing) — [Kestra blog: YAML pitfalls](https://kestra.io/blogs/2023-12-01-yaml-pitfalls) (2023, older) +- 2.0 brings many breaking changes and requires migrating through 1.3.x first — [migration guide](https://kestra.io/docs/migration-guide/v2.0.0) +- "Business-process or app-centric automation is usually easier in n8n" — [ZoomInfo](https://pipeline.zoominfo.com/sales/kestra-vs-n8n) + +### Inferences +- The biggest practical limitation for an n8n replacement is that OSS has a single Basic Auth user with no RBAC or SSO. A team would have to buy EE or accept one shared credential. + +### Gaps +- No primary Reddit or HN threads were retrieved; searches returned none. The criticisms above come from review aggregators and are of medium-low reliability. +- G2 and Gartner reviews were not retrieved. diff --git a/docs/research/notes/n8n-feature-feasibility.md b/docs/research/notes/n8n-feature-feasibility.md new file mode 100644 index 0000000..1ccc951 --- /dev/null +++ b/docs/research/notes/n8n-feature-feasibility.md @@ -0,0 +1,143 @@ +> Ported from earlier research (2026-10-29) and sanitized for clean-room use: source-code-derived details removed. Not legal advice. + +# n8n Gated Features: What's Restricted in Community Edition and How Each Could Be Provided Independently + +Research date: 2026-10-29. Marking: **[V]** = verified this session from a fetched source; **[K]** = from background knowledge (pre-2026), not re-verified this session. Treat [K] as needing a check. No license-key bypass content is included. The "external means" listed below are sidecars, proxies, documented extension points, or separate tools. None of them modify n8n's Enterprise-licensed code. Licensing analysis is in [n8n-licensing-legal.md](n8n-licensing-legal.md). + +Sanitization note: internal database table names, internal (non-public) API paths and descriptions of n8n's internal code structure have been generalized or removed. Environment variables, CLI commands, public API endpoints and expression syntax below are as documented by n8n for users. + +--- + +## Q1. What is gated, on which plan, and at what price (2025-2026)? + +### Takeaway +n8n Cloud has three self-serve plans: Starter €20/mo (2.5K executions), Pro €50/mo (10K), and Business €667/mo (40K), all billed annually. Business is self-hosted only, with Cloud on a waitlist. Enterprise is priced by sales. The self-hosted Community Edition (CE) leaves out SSO/LDAP, projects, sharing, variables, environments/git, external secrets, external binary storage, log streaming, and multi-main. A free "registered community" key unlocks folders, debug-in-editor, and custom execution data. + +### Cited Findings +- Plans and prices (annual billing, EUR; the page shows no monthly or USD prices): Starter €20/mo, hosted, 2.5K executions/mo. Pro €50/mo, hosted, 10K. Business €667/mo, "self-hosted only (Cloud waitlist)", 40K. Enterprise: contact sales, hosted or self-hosted, custom volume, SLA. CE is self-hosted from GitHub with no price — [n8n pricing](https://n8n.io/pricing/) [V] +- Shared projects: Starter 1, Pro 3, Business 6, Enterprise unlimited — [n8n pricing](https://n8n.io/pricing/) [V] +- Concurrent executions (cloud): Starter 5. Pro "20 / 50" in the table but "up to 50" on the plan card, so the page contradicts itself. Enterprise 200+ — [n8n pricing](https://n8n.io/pricing/) [V] +- Execution log retention: Starter 7 days, Pro 30 days, Enterprise unlimited. Max saved executions: 2.5k / 25k / 50k — [n8n pricing](https://n8n.io/pricing/) [V] +- Workflow history: Starter 1 day, Pro 5 days, Enterprise 365+ days — [n8n pricing](https://n8n.io/pricing/) [V]. The docs say versions from the last 24 hours are available to all users, full history needs Enterprise, and Cloud Pro gets 5 days — [n8n docs: workflow history](https://docs.n8n.io/workflows/history) [V, via search summary]. A third-party Activepieces blog (2026-10-27) gives 30 days for Business self-hosted and 1 day for Community — [Activepieces blog](https://www.activepieces.com/blog/n8n-workflow-history-retention-and-how-to-restore.md) [V, secondary and from a competitor] +- Insights: Starter gets the overview banner only. Pro gets a dashboard with a 7-14 day filter. Business 30 days. Enterprise covers 24h-365 days at hourly, daily, or weekly granularity — [n8n pricing](https://n8n.io/pricing/) [V]. The docs say the 7-day summary banner appears on all plans and the dashboard is Pro (limited) and Enterprise only. `N8N_INSIGHTS_MAX_AGE_DAYS` defaults to 365, and `N8N_DISABLED_MODULES=insights` turns insights off — [n8n docs: insights](https://docs.n8n.io/insights) [V, via search summary] +- SSO and LDAP: Business and Enterprise only (not Starter or Pro) — [n8n pricing](https://n8n.io/pricing/) [V]. OIDC setup is documented as an Enterprise feature — [n8n docs: OIDC setup](https://docs.n8n.io/user-management/oidc/setup) [V, via search snippet] +- Roles: Admin roles and instance admins are Pro and above. Project editors are Pro and above, while Starter has project admins only. Project viewers and custom roles are Enterprise only — [n8n pricing](https://n8n.io/pricing/) [V]. The docs say the Editor role is on Cloud Pro and self-hosted Enterprise, and Viewer is on Cloud Enterprise and self-hosted Enterprise — [n8n docs: role types](https://docs.n8n.io/user-management/rbac/role-types/) [V] +- Global variables: Pro and Enterprise. Multiple environments and git version control: Business and Enterprise (Enterprise includes dev and prod instances). Workflow Diff, external secret store, log streaming, audit logging, execution data redaction, enforced instance-wide 2FA, worker view, and "End-user credentials (preview)": Enterprise only on the comparison table. Multi-main: "Coming soon" on Enterprise in the cloud table — [n8n pricing](https://n8n.io/pricing/) [V] +- Queue mode on the cloud pricing table: No for Starter/Pro, Yes for Business/Enterprise. This is about cloud plans. Self-hosted CE can run queue mode (see Q2) — [n8n pricing](https://n8n.io/pricing/) [V]; CE queue mode [K] +- Debug in editor: Starter, Pro, and Enterprise. Search executions by their data: Pro and above — [n8n pricing](https://n8n.io/pricing/) [V] +- AI Assistant: preview on Starter (1,600 credits/mo) and Pro (up to 9,600/mo; the FAQ mentions 4,000 or 9,600). On self-hosted it runs in preview with your own API key and has no credit limits — [n8n pricing](https://n8n.io/pricing/) [V] +- Log streaming is on Cloud Enterprise and self-hosted Enterprise. Destinations are syslog, generic webhook, and Sentry. Event categories are workflow, node, audit (user/credential/workflow/variable/external-secrets/package/role-mapping/token-exchange/MCP), worker, AI node, runner, and queue (enqueued/dequeued/completed/failed/stalled) — [n8n docs: log streaming](https://docs.n8n.io/log-streaming/) [V] +- **Excluded from CE**: Custom variables, Environments, External secrets, External storage for binary data, Log streaming, Multi-main mode, Projects, SSO (SAML, LDAP), Sharing of workflows and credentials, Version control using Git — [n8n docs: Community Edition features](https://docs.n8n.io/hosting/community-edition-features/) [V] +- **Unlocked in CE by the free registered community license key**: Folders, Debug in editor, Custom execution data (save, find, and annotate execution metadata) — [n8n docs: CE features](https://docs.n8n.io/hosting/community-edition-features/) [V] +- Business/Enterprise is required for the `s3` and `azure` values of `N8N_EXECUTION_DATA_STORAGE_MODE` (external storage) — [n8n docs: executions env vars](https://docs.n8n.io/hosting/configuration/environment-variables/executions/) [V] +- `N8N_CONCURRENCY_EVALUATION_LIMIT` depends on tier: 1 on CE and Cloud Pro, 3 on self-hosted Business, 5 on Enterprise. Setting the variable overrides the tier default — [n8n docs: executions env vars](https://docs.n8n.io/hosting/configuration/environment-variables/executions/) [V] +- n8n 2.0 (December 2025) added isolated task runners, which are secure by default, and a publish/save model that separates drafts from live workflows — [jimmysong.io deep dive](https://jimmysong.io/en/blog/n8n-deep-dive/) [V, secondary] + +### Inferences +- Business (€667/mo, self-hosted) is the cheapest plan with SSO, git, environments, and queue mode. Many "Enterprise" rows (log streaming, external secrets, audit, worker view) are not shown on the Business card, so Business may not have them. Confirm with sales. +- The pricing table describes cloud plans. Self-hosted CE gating follows the CE features doc instead. For example, queue mode and concurrency limits run on CE without a license. + +### Gaps +- The pricing page does not give monthly or USD prices. Older Business pricing (e.g. €800/mo) is not confirmed here. +- Whether Business self-hosted includes log streaming, external secrets, and audit logs is not shown on the page. +- I did not verify whether CE still limits the number of users. Background knowledge [K]: CE allows an owner plus invited members, but members cannot share workflows or credentials, and admin roles are gated. +- Whether "Folders" is on paid cloud plans is not listed in the pricing table. + +--- + +## Q2. What is already free in CE, and how could each gated feature be provided externally? (per-feature table) + +### Takeaway +Several "gated" capabilities have free near-equivalents. Pruning and concurrency use environment variables. Queue mode, the `/metrics` endpoint, the public REST API, CLI export/import, and external backend hooks are all available on CE. That leaves real gaps in four places: in-product identity (SSO, RBAC, sharing), live log streaming of audit events, external secrets, and multi-main HA. All four can be approximated with proxies, sidecars, and scripts. For STaurtomation, the table doubles as a list of capabilities users expect and of the operational knobs they are used to. + +### Cited Findings +- Pruning env vars are not license-gated: `EXECUTIONS_DATA_PRUNE` (default true), `EXECUTIONS_DATA_MAX_AGE` (default 336 hours = 14 days), `EXECUTIONS_DATA_PRUNE_MAX_COUNT` (default 10000; 0 = no limit), `EXECUTIONS_DATA_HARD_DELETE_BUFFER` (1h), `..._HARD_DELETE_INTERVAL` (15 min), `..._SOFT_DELETE_INTERVAL` (60 min) — [n8n docs: executions env vars](https://docs.n8n.io/hosting/configuration/environment-variables/executions/) [V] +- `N8N_CONCURRENCY_PRODUCTION_LIMIT` (default -1, meaning no limit in regular mode) is not marked as license-gated — [same](https://docs.n8n.io/hosting/configuration/environment-variables/executions/) [V] +- The `/metrics` Prometheus endpoint is enabled with `N8N_METRICS=true` (off by default). It is available on self-hosted in all editions, but not on n8n Cloud. `/healthz` and `/healthz/readiness` (DB connected and migrated) are always on. Health checks on queue workers need `QUEUE_HEALTH_CHECK_ACTIVE=true` — [n8n docs: monitoring](https://docs.n8n.io/hosting/logging-monitoring/monitoring/) [V] +- External backend hooks are registered with `EXTERNAL_HOOK_FILES`. They are plain JS files that run server-side and include hooks such as `n8n.ready` and `frontend.settings` — [n8n docs: external hooks](https://docs.n8n.io/hosting/configuration/external-hooks) [V, via search summary]. External hooks are not on the CE exclusion list, and a community member reports they work without a license key — [community thread, 2026-03/04](https://community.n8n.io/t/question-about-sso-via-custom-hooks-and-sul-compliance/283373) [V] +- A NixOS deployment puts n8n behind oauth2-proxy with Kanidm. An external hook logs users in automatically from the `X-Email` header. The hook code is not shown — [git.thalheim.io dotfiles](https://git.thalheim.io/janet/dotfiles/src/branch/main/machines/eve/modules/n8n) [V, via search summary] +- `cweagans/n8n-oidc` describes itself as "bolt-on OIDC support for n8n" (JavaScript). An aggregator lists its last push as 2025-12-29 with 2 open issues. I did not check this on GitHub — [GitTrend](https://gittrend.io/repo/cweagans/n8n-oidc) [V, aggregator]. A forum reply also names `n8n-oidc` and `n8n-community-sso`. A search for the latter found no such project — [community thread](https://community.n8n.io/t/question-about-sso-via-custom-hooks-and-sul-compliance/283373) [V] +- Proxy-gateway SSO is a known pattern: Authelia, Authentik, Pomerium, or Cloudflare Access enforce IdP MFA and groups before a request reaches n8n. n8n's own login still applies unless a hook maps the header to a session — [lumadock guide](https://lumadock.com/tutorials/n8n-sso-options) (403 on fetch; content seen only as a search summary) [V-partial]. Header trust is safe only if the backend is reachable solely through the proxy — [Authelia nginx docs](https://gitea.unej.ac.id/techies/authelia/raw/commit/bd5bb497e3cbcb6c54f1b150db70a97564e6b6ee/docs/proxies/nginx.md) [V, via search] +- Git backup and sync community tooling: n8n.io template 12721 offers bidirectional GitHub sync. It detects new, edited, renamed, and deleted workflows, runs a daily backup, and has a manual restore path — [n8n template 12721](https://n8n.io/workflows/12721-back-up-and-restore-n8n-workflows-with-github-sync/). Template 7304 does backups with change detection and name-based filenames — [n8n template 7304](https://n8n.io/workflows/7304-automated-workflow-backup-with-intelligent-change-detection-using-github/). The forum's "Ultimate GitHub ↔ n8n Workflow Backup System" adds a UI and lets you import from any commit — [community.n8n.io](https://community.n8n.io/t/the-ultimate-github-n8n-workflow-backup-system-with-ui-and-commit-level-visibility/181003). `wapad/n8n-data-manager` is a shell script that backs up and restores workflows, credentials, and env to GitHub — [ecosyste.ms topic](https://repos.ecosyste.ms/topics/workflow-backup) [V, via search] +- [K] CLI: `n8n export:workflow --all --separate --backup --output=dir/`, `n8n export:credentials --all [--decrypted]`, `n8n import:workflow --separate --input=dir/`, `n8n import:credentials`. Public REST API (`/api/v1/workflows`, `/executions`, `/credentials`, `/tags`) with `X-N8N-API-KEY`, available on CE. Security audit with `n8n audit` CLI / `POST /api/v1/audit` (risk report, not an event log). Logging with `N8N_LOG_LEVEL` and `N8N_LOG_OUTPUT=console,file`, `N8N_LOG_FILE_LOCATION`. Credential overwrites with `CREDENTIALS_OVERWRITE_DATA` (JSON per credential type) or `CREDENTIALS_OVERWRITE_ENDPOINT`. Docker secrets through `_FILE`-suffixed env vars. Queue mode with `EXECUTIONS_MODE=queue` plus Redis (`QUEUE_BULL_REDIS_*`) and `n8n worker` processes. Error Workflow (Error Trigger node) is free. + +### Per-feature table + +| Feature | Gated on (plan) | Free in CE today | External / independent approach (no edits to Enterprise-licensed code) | Clean-room in-product difficulty | Community projects | +|---|---|---|---|---|---| +| **SSO – SAML** | Business+, Enterprise [V] | Email/password login, 2FA per user [K] | A forward-auth proxy (Authelia/Authentik/Pomerium/oauth2-proxy/Cloudflare Access) in front of n8n gates access, but users then hit n8n's login again. Removing the second login takes an external hook that reads the trusted header and issues the session cookie (thalheim pattern). SAML IdP → proxy (Authentik/Keycloak can bridge SAML to OIDC). | Medium-High: auth middleware, JIT provisioning, cookie/JWT issuance, mapping onto the user model | cweagans/n8n-oidc; thalheim oauth2-proxy+hook; lumadock guide | +| **SSO – OIDC** | Enterprise per docs; pricing card says "SSO" on Business [V] | — | Same as above. oauth2-proxy/Pomerium are native OIDC. A hook-based OIDC callback is what n8n-oidc does. | Medium | cweagans/n8n-oidc | +| **LDAP** | Business+, Enterprise [V] | — | Authelia/Authentik/Keycloak with an LDAP backend → forward-auth headers → hook. Or a cron job that syncs LDAP users into n8n via invites. [K: the public API's user endpoints may need an owner key] | Medium | none found specifically | +| **User mgmt / RBAC** (instance admin, project admin/editor/viewer, custom roles) | Admin: Pro+. Editor: Pro (cloud) / Enterprise (self-host). Viewer and custom roles: Enterprise [V] | Owner + members [K] | You cannot add real per-object authorization from outside. Options: separate n8n instances per team/trust boundary (one owner each); a proxy that restricts write methods per group (a crude, fragile read-only "viewer"); expose workflows to non-editors through webhooks/forms only | High: per-object authorization must be enforced on every API endpoint and UI view | none robust found | +| **Projects (count limits) / sharing** | Projects excluded from CE; Starter 1 / Pro 3 / Business 6 / Ent unlimited shared projects [V] | Personal space per user; tags; Folders (registered key) [V] | One instance per team; tags and folders as soft grouping; a git repo per team using the export/import scripts | High: tied to the RBAC data model | — | +| **Workflow & credential sharing** | Excluded from CE [V] | — | Shared service account (the owner) with distributed login, which is weak for audit. Credentials injected via `CREDENTIALS_OVERWRITE_DATA` so every user's node of a given type gets the same secret [K]. Export/import workflows between users via CLI/API | High | — | +| **Log streaming** (syslog/webhook/Sentry) | Enterprise [V] | `/metrics` Prometheus (self-host, all editions) [V]; console/file logs [K]; Error Trigger workflows [K]; execution records in the DB | (1) Ship `N8N_LOG_OUTPUT=file` / container stdout with Vector/Fluent Bit/Promtail to syslog/Loki/Datadog. (2) Postgres logical replication or Debezium CDC on the execution tables to get workflow-level events. (3) Prometheus scrape of `/metrics` plus Alertmanager. (4) A global Error Workflow that posts to a webhook or Sentry. (5) External hooks on workflow lifecycle events [K; check the docs for hook names]. Node-level and audit events are the hard part. | Medium: delivering events to destinations is easy; producing node and audit events needs in-process hooks | none specific found | +| **Execution retention / pruning** | Cloud plans cap retention (7d / 30d / unlimited) [V] | **Fully free** on self-host via `EXECUTIONS_DATA_PRUNE`, `_MAX_AGE`, `_PRUNE_MAX_COUNT` [V]; `EXECUTIONS_DATA_SAVE_ON_SUCCESS/ERROR` [K] | Already free. For longer archives, copy execution rows to cold storage before pruning (cron + pg_dump or COPY) | N/A (free) | — | +| **Insights** | Dashboard: Pro (limited) / Enterprise (full) [V] | Summary banner (7 days) on all plans [V]; insights data is collected on CE (`N8N_INSIGHTS_MAX_AGE_DAYS` default 365) [V] | Grafana on Postgres execution data or Prometheus `/metrics` counters. Metabase/Superset dashboards | Low-Medium: it's an aggregation UI over existing data | Grafana n8n dashboards exist [K] | +| **Multiple environments / git source control** | Business+, Enterprise [V]; excluded from CE [V] | CLI export/import, public API [K] | Separate dev/stage/prod instances (distinct DB, same `N8N_ENCRYPTION_KEY` only if moving encrypted creds). CI (GitHub Actions/GitLab) runs `n8n export:workflow --backup --separate` → commit → PR review → `n8n import:workflow` or API PUT on prod. Strip/re-map credential IDs per environment. | Medium: serializing workflows is simple, but merge, conflict, and credential-stub mapping take work | templates 12721, 7304, the forum UI system, wapad/n8n-data-manager | +| **Workflow history / versions / diff** | CE: 24h (docs) [V]; Pro 5d; Ent 365+ days; Diff Ent only [V] | Last 24h versions [V] | A git backup on every change (cron every N min or a public-API poll for recently updated workflows) gives unlimited history. `git diff` / `jq`-normalized JSON diff. Restore with import | Low-Medium | same git-backup tools | +| **Variables (`$vars`)** | Pro+ cloud; excluded from CE [V] | Env vars via `$env` in expressions [K, may be blocked by `N8N_BLOCK_ENV_ACCESS_IN_NODE`, default true in v2 per n8n 2.0 hardening — unverified] | Use `$env` (set `N8N_BLOCK_ENV_ACCESS_IN_NODE=false`), a "config" sub-workflow or Data Table read at start, or a static JSON file loaded via Read File node | Low | — | +| **External secrets** (Vault, AWS SM, Azure KV, GCP SM, Infisical) | Enterprise (pricing table) [V]; excluded from CE [V] | `CREDENTIALS_OVERWRITE_DATA` / `_ENDPOINT` [K]; `_FILE` env vars [K] | A sidecar (Vault Agent, External Secrets Operator in Kubernetes, Infisical agent, AWS Secrets CSI) renders secrets into env or a file at pod start. Feed them into `CREDENTIALS_OVERWRITE_DATA`, or have a cron job update credentials via the public API (create/delete; update support [K, uncertain]). Or call the Vault/AWS API at runtime inside a workflow via HTTP node (bootstrap token still needed) | Medium: provider adapters + expression resolution `{{ $secrets.x }}` | none specific found | +| **Audit logs** | Enterprise [V] | `n8n audit` security risk report [K]; workflow update timestamps and history | DB triggers or CDC on the workflow, credential and user tables; reverse-proxy access logs (method + path + header identity) give a who-did-what HTTP trail; external hooks for workflow create/update/delete [K] | Medium | — | +| **Queue mode / workers** | Cloud: Business+ [V] | **Free on self-host**: `EXECUTIONS_MODE=queue` + Redis + `n8n worker` [K] | Already free. Scale workers with Kubernetes HPA/KEDA on Redis queue length | N/A | n8n Helm charts (community) [K] | +| **Worker view** | Enterprise [V] | Worker `/healthz` (`QUEUE_HEALTH_CHECK_ACTIVE`) [V]; `/metrics` [V] | Grafana panel from worker `/metrics` + Bull queue metrics from Redis (bull-board, redis-exporter) | Low | bull-board (generic BullMQ UI) [K] | +| **Multi-main HA** | Excluded from CE [V]; Enterprise [V] | Single main + many workers [K] | Active/passive: one main replica plus a fast restart (Kubernetes liveness), with Postgres HA. Separate webhook processors (`n8n webhook`) in queue mode take ingress load [K]. True active-active needs leader election for triggers/cron, which is the hard part. | High: leader election, pub/sub coordination, trigger deduplication | — | +| **Debug in editor** | Free with registered CE key [V] | Yes (registered) [V] | — | — | — | +| **Execution search / custom data** | Search by data: Pro+ cloud [V]; custom execution data free with registered key [V] | Custom data (registered) [V] | Full-text search via Postgres on execution data (JSON) or ETL into OpenSearch | Low-Medium | — | +| **Folders** | Free with registered CE key [V] | Yes (registered) [V] | — | — | — | +| **Concurrency limits** | Cloud caps 5/20-50/200+ [V] | **Free**: `N8N_CONCURRENCY_PRODUCTION_LIMIT` [V] | Already free | N/A | — | +| **External binary storage (S3/Azure)** | Business/Enterprise [V] | Filesystem / DB mode [K] | Mount S3 through a FUSE or CSI driver (s3fs, mountpoint-s3) into the filesystem binary-data path. Performance caveats apply | Medium | — | +| **AI Assistant credits** | Cloud credits: 1,600 Starter / up to 9,600 Pro [V] | Self-hosted: preview with own API key, no credit limit [V] | Use own LLM keys; the AI Agent nodes are free; an external MCP/LLM coding assistant can generate workflow JSON | N/A | — | + +### Inferences +- External hooks are the key enabler for SSO on stock n8n without touching Enterprise-licensed code. They work without a license in practice, though n8n has not ruled on whether using them this way complies with its license (see Q3). They run inside the n8n process, so they can break on upgrades. Pin versions and test them in CI. +- n8n does not natively honor forwarded identity headers in CE. I found no documented trusted-header login. A proxy alone gives an access gate on top of n8n's login, not seamless SSO. Seamless SSO needs a hook such as the thalheim `X-Email` hook or n8n-oidc. +- Retention, concurrency, queue mode, and `/metrics` are gated only on cloud. On self-host they are free, so they need no reimplementation. +- RBAC, sharing, and multi-main are the hardest to provide from outside. Separate instances per team is the most robust workaround. + +### Gaps +- The cweagans/n8n-oidc README, its mechanism, and its compatibility with n8n 2.x were not verified on GitHub. +- Exact hook names for workflow lifecycle events and the current `N8N_BLOCK_ENV_ACCESS_IN_NODE` default in v2 were not re-verified. +- Whether the public API supports updating existing credentials (vs. create/delete) in current versions was not verified. +- I found no community project specifically doing external-secrets or log-streaming sidecars for n8n. + +--- + +## Q3. Legal/technical constraints on a clean-room reimplementation + +### Takeaway +n8n uses the Sustainable Use License (SUL). It allows internal-business use and modification but restricts commercial resale and hosting. Files carrying the Enterprise Edition marker fall under the separate n8n Enterprise License. Whether an independently written SSO built on hooks complies with the license is officially unresolved. A community user asked n8n licensing in March 2026 and had no answer as of April 8, 2026. Full analysis: [n8n-licensing-legal.md](n8n-licensing-legal.md). + +### Cited Findings +- Fair-code / SUL: anyone may use and modify the source for free, but commercial resale as a hosted service is restricted. Free self-hosting is allowed for internal use, and commercial hosting or embedding needs a paid license — [Sacra](https://sacra.com/c/n8n/) [V, secondary] +- The question of building one's own OIDC SSO via hooks without n8n-derived code was asked on 2026-03-31. Replies argued hooks are an ungated CE feature and the approach "sounds reasonable", and advised contacting license@n8n.io. The asker had emailed and received no response by 2026-04-08. No n8n staff confirmation appears in the thread — [community.n8n.io thread](https://community.n8n.io/t/question-about-sso-via-custom-hooks-and-sul-compliance/283373) [V] +- The n8n repo has `LICENSE.md` (SUL) and `LICENSE_EE.md` (n8n Enterprise License, covering Enterprise-marked files). Using the EE code in production requires a valid enterprise license — [LICENSE_EE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE_EE.md) + +### Inferences +- The lowest-risk approach for n8n users is purely external: proxies, CI scripts, sidecars, and DB/metrics scraping. Hook-based in-process features sit in a grey area. Anything that patches or replaces Enterprise-licensed modules, or interferes with license checks, is out of bounds (license-key bypass excluded per scope). +- Even a clean-room in-product feature forked into n8n stays under SUL for the rest of the codebase. That fork cannot be offered commercially as a hosted service. An independent codebase (STaurtomation's model) is not subject to the SUL. + +### Gaps +- No official n8n statement on hook-based SSO was found. + +--- + +## Q4. Alternatives (open-source workflow tools) and their own gating; n8n forks + +### Takeaway +Most "open-core" alternatives gate the same enterprise set as n8n: SSO, RBAC, audit, git, and secrets. Truly ungated options are general-purpose orchestrators or simpler tools: Node-RED, Huginn, Airflow, and Temporal. Kestra and Windmill are OSI-licensed at the core but still gate SSO/RBAC/audit. See also the [Kestra/Windmill/Activepieces comparison](../reports/kestra-windmill-activepieces-comparison.md). + +### Cited Findings +- **Windmill** Community Edition caps SSO users at 10, users at 50, workspaces at 3, and groups at 4. Git sync works for up to 2 users. There are no audit logs, no external secret backends (Vault/AKV/AWS SM), no multiplayer, no agent workers, no worker-group management UI, no autoscaling, and no concurrency limits. SAML and SCIM are Enterprise — [Windmill pricing](https://www.windmill.dev/pricing) [V]. The license is not stated on the pricing page. [K] The core is AGPLv3, with EE features under a proprietary license. +- **Activepieces** pricing: Free $0 (1,000 credits, 5 users), Plus $20/mo, Team $200/mo (25 users, SSO and standard roles), Ultimate custom (SCIM, custom RBAC, audit logs, secret managers, Git sync/releases, branding), Embed from $36k/yr — [Activepieces pricing](https://www.activepieces.com/pricing) [V]. The core is MIT; enterprise code is under a commercial license — [Activepieces license docs](https://www.activepieces.com/docs/about/license) [V, via search]. Sources disagree on whether CE lacks projects, SSO, audit, and Git sync (third-party summary) or has "all features" (vendor editions page) — [editions](https://activepieces.com/docs/about/editions) [V, conflicting] +- **Kestra** OSS is Apache 2.0 at $0 and includes Git integration/versioning. Enterprise adds SSO (OIDC, LDAP, SCIM), RBAC, audit logs, secrets managers, multi-tenancy, worker groups, and namespace-level secrets/variables. It is sold as an annual per-instance subscription with no listed price — [Kestra pricing](https://kestra.io/pricing) [V] +- [K, not re-verified] **Node-RED**: Apache-2.0, no paid tier in core. Its multi-user/auth support is basic (admin auth with a passport strategy allows OIDC/OAuth). FlowFuse sells team and enterprise features. **Huginn**: MIT, fully free, multi-user, aging. **Automatisch**: AGPL-3.0 core with enterprise features under a commercial license (SSO/SAML gated). **Apache Airflow**: Apache-2.0, all features free (RBAC, OAuth/LDAP via FAB auth manager, logs to remote stores), but it is code-first, not low-code. **Temporal**: MIT server, all features free self-hosted (Temporal Cloud is paid); code-first. +- This part of the research (search-engine results only) found no reporting of an n8n fork that unlocks enterprise features — [search results summary](https://jimmysong.io/en/blog/n8n-deep-dive/) [V, negative result]. The licensing research did find that such forks exist; see [n8n-licensing-legal.md §7](n8n-licensing-legal.md) (they are not named). + +### Inferences +- If you need SSO and RBAC for free, the closest low-code fit is Node-RED (OIDC via admin auth, permissions coarse). Code-first stacks like Airflow and Temporal are fully free but are a different paradigm. Windmill CE gives 10 SSO users free, which is the most generous of the open-core options. +- n8n forks would inherit SUL restrictions. Any fork that unlocks Enterprise-licensed code would violate the Enterprise License. + +### Gaps +- Licenses and gating for Node-RED/FlowFuse, Huginn, Automatisch, Airflow, Temporal, and Windmill were not re-verified this session. +- No systematic GitHub search for n8n forks was done (search engine results only). diff --git a/docs/research/notes/n8n-licensing-legal.md b/docs/research/notes/n8n-licensing-legal.md new file mode 100644 index 0000000..6247964 --- /dev/null +++ b/docs/research/notes/n8n-licensing-legal.md @@ -0,0 +1,257 @@ +> Ported from earlier research (2026-10-29) and sanitized for clean-room use: source-code-derived details removed. Not legal advice. + +# n8n Licensing and the Legal Feasibility of a Clean-Room Reimplementation of Enterprise-Gated Features + +> Research notes compiled 2026-10-29. NOT legal advice. License texts were fetched verbatim from the `master` branch on 2026-10-29. Points about legal doctrine come from secondary sources (law-firm alerts, case summaries) unless marked otherwise. US and EU positions differ materially, and the differences are flagged throughout. n8n GmbH is a Berlin company. Neither license names a governing law, so which law applies is itself uncertain (see Gaps). +> +> Sanitization note: findings from a repository scan or source read of n8n (file counts, file paths, internal package names, how the license check is implemented) have been removed. Where the license text names the Enterprise Edition filename marker, it is paraphrased as [the "ee" marker] to keep this file free of path patterns. + +--- + +## 1. Sustainable Use License (LICENSE.md): exact text and key clauses + +### Takeaway +The SUL v1.0 is a short permissive-style grant ("use, copy, distribute, make available, and prepare derivative works"). It has three limitations: (a) use or modify only for internal business, non-commercial or personal purposes; (b) distribute only free of charge for non-commercial purposes; (c) do not alter, remove or obscure licensing, copyright or other *notices*. Violating it automatically terminates the license, with a 30-day cure period after notice. **It does not contain the "license key functionality" clause found in the Elastic License 2.0, which it is otherwise modelled on.** That clause has been dropped. + +### Cited Findings +- **Scope preamble (verbatim except for the bracketed paraphrase):** "Content of branches other than the main branch (i.e. "master") are not licensed." / "Source code files that contain [the "ee" marker] in their filename or [the "ee" marker] in their dirname are NOT licensed under the Sustainable Use License. To use source code files that contain [the "ee" marker] in their filename or [the "ee" marker] in their dirname you must hold a valid n8n Enterprise License specifically allowing you access to such source code files and as defined in "LICENSE_EE.md"." / "All third party components incorporated into the n8n Software are licensed under the original license provided by the owner of the applicable component." / "Content outside of the above mentioned files or restrictions is available under the "Sustainable Use License"" — [n8n LICENSE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE.md) +- **Acceptance (verbatim):** "By using the software, you agree to all of the terms and conditions below." — [LICENSE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE.md) +- **Copyright License (verbatim):** "The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject to the limitations below." — [LICENSE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE.md) +- **Limitations (verbatim, complete):** "You may use or modify the software only for your own internal business purposes or for non-commercial or personal use. You may distribute the software or provide it to others only if you do so free of charge for non-commercial purposes. You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software. Any use of the licensor's trademarks is subject to applicable law." — [LICENSE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE.md) +- **Patents (key sentences, verbatim):** "This license does not cover any patent claims that you cause to be infringed by modifications or additions to the software. If you or your company make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately." — [LICENSE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE.md) +- **Notices (verbatim):** "You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms. If you modify the software, you must include in any modified copies of the software a prominent notice stating that you have modified the software." — [LICENSE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE.md) +- **No Other Rights (verbatim):** "These terms do not imply any licenses other than those expressly granted in these terms." — [LICENSE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE.md) +- **Termination (verbatim):** "If you use the software in violation of these terms, such use is not licensed, and your license will automatically terminate. If the licensor provides you with a notice of your violation, and you cease all violation of this license no later than 30 days after you receive that notice, your license will be reinstated retroactively. However, if you violate these terms after such reinstatement, any additional violation of these terms will cause your license to terminate automatically and permanently." — [LICENSE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE.md) +- **Definitions (verbatim, selected):** "“Use” means anything you do with the software requiring your license." "“Your company” is any legal entity ... that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization." "“Trademark” means trademarks, service marks, and similar rights." — [LICENSE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE.md) +- The phrase "internal business purposes" is not defined in the license. n8n's FAQ gives its own reading: "If workflows are only created or modified by you or people in your organization, you can use n8n under the Community license for free." — [n8n License FAQ](https://docs.n8n.io/n8n-community-license/community-license/license-faq) +- **License-file history (git log of LICENSE.md):** changed to SUL on 2022-03-17 ("Change to the Sustainable Use License #2932"); Enterprise License introduced 2022-08-29 (PR #3945); scoped to master branch 2022-10-26 (PR #4450); "Elaborate scope of Sustainable Use License" 2024-04-27 (PR #9233); "Mark all backend Enterprise Edition files and dirs" 2024-12-24 (PR #12350). — [GitHub commit history for LICENSE.md](https://github.com/n8n-io/n8n/commits/master/LICENSE.md) +- **Structural comparison:** the Elastic License 2.0 has the same notice sentence word for word ("You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software. Any use of the licensor's trademarks is subject to applicable law.") and nearly the same patent clause. It *also* has: "You may not move, change, disable, or circumvent the license key functionality in the software, and you may not remove or obscure any functionality in the software that is protected by the license key." The SUL leaves this sentence out. — [Elastic License 2.0 (SPDX)](https://spdx.org/licenses/Elastic-2.0.html); [LICENSE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE.md) + +### Inferences +- The SUL was evidently derived from ELv2: it shares ELv2's structure, patent clause, notice clause, termination and definitions. Leaving out ELv2's license-key clause therefore looks like a deliberate drafting choice, or at least a choice n8n will have trouble explaining away. Under the SUL's own "No Other Rights" clause and ordinary contra proferentem reasoning (ambiguity is read against the drafter), it is hard to stretch the "notices" clause to cover license-key *functionality*. +- The termination wording "such use is not licensed" makes the limitations work as scope conditions rather than mere covenants. Use outside them is arguably unlicensed and so potential copyright infringement, not just breach of contract (see §5, MDY v. Blizzard). + +### Gaps +- There is no published court decision interpreting the SUL, and I found no law-firm analysis devoted specifically to it. +- The SUL has no governing-law or venue clause. Whether German, EU or US law governs a dispute is unresolved. + +--- + +## 2. n8n Enterprise License (LICENSE_EE.md) for Enterprise-marked files + +### Takeaway +The Enterprise License is a restrictive proprietary license. It allows production use only with a valid paid n8n Enterprise license, and it assigns all rights in any modifications or patches to n8n. It permits copying and modifying for development and testing without a subscription. Beyond that, copying, merging, publishing, distributing, sublicensing and selling are forbidden. It too has no explicit "license key circumvention" sentence, but using Enterprise-licensed code in production without a license is plainly outside the grant. + +### Cited Findings +- **Full operative text (verbatim):** "This software and associated documentation files (the "Software") may only be used in production, if you (and any entity that you represent) hold a valid n8n Enterprise license corresponding to your usage. Subject to the foregoing sentence, you are free to modify this Software and publish patches to the Software. You agree that n8n and/or its licensors (as applicable) retain all right, title and interest in and to all such modifications and/or patches, and all such modifications and/or patches may only be used, copied, modified, displayed, distributed, or otherwise exploited with a valid n8n Enterprise license for the corresponding usage. Notwithstanding the foregoing, you may copy and modify the Software for development and testing purposes, without requiring a subscription. You agree that n8n and/or its licensors (as applicable) retain all right, title and interest in and to all such modifications. You are not granted any other rights beyond what is expressly stated herein. Subject to the foregoing, it is forbidden to copy, merge, publish, distribute, sublicense, and/or sell the Software." — [n8n LICENSE_EE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE_EE.md) +- Copyright line: "Copyright (c) 2022-present n8n GmbH." — [LICENSE_EE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE_EE.md) +- n8n's docs summarize: the SUL covers the main repo except "Content of branches other than master" and source code files carrying the Enterprise marker in their file name, which "are licensed under the n8n Enterprise License." — [n8n docs: Sustainable Use License](https://docs.n8n.io/n8n-community-license/sustainable-use-license) + +### Inferences +- Modifying Enterprise-licensed files is a trap. Under the EE license n8n "retain[s] all right, title and interest" in your modifications and patches. Any derivative of that code is effectively n8n's and usable only with a license. A reimplementation must not be derived from it. +- The "development and testing" carve-out lets engineers lawfully read and run Enterprise code in non-production settings. For clean-room purposes that is a contamination vector, not a safe harbor: anyone who has studied it should not write the replacement. STaurtomation goes further and excludes anyone who has read any n8n source, or source-derived descriptions of it. + +### Gaps +- How n8n's commercial Enterprise agreements (the separate signed contracts) define circumvention is not public. + +--- + +## 3. Does the SUL forbid modifying license checks, removing gating, or writing NEW equivalent code inside a fork? + +### Takeaway +On the license *text*: (a) the SUL expressly allows modification for internal business, non-commercial and personal purposes. (b) Its only anti-tampering sentence covers *notices*, not license-key functionality. (c) It says nothing against writing new, original code. So a fork that deletes all Enterprise-licensed code and adds independently written replacements is arguably permitted *for internal or non-commercial use*. n8n's *published position* is more restrictive (its FAQ lists "Use enterprise features that ask for a license key without an Enterprise license" and "Fork n8n's code to launch your own automation product" as prohibited). Selling or hosting such a fork for others is clearly prohibited by the SUL's use and distribution limits, whatever the gating question. This is the least settled area and needs counsel. It does not affect STaurtomation, which is an independent codebase, not a fork. + +### Cited Findings +- SUL grant includes "prepare derivative works" and "You may use or modify the software only for your own internal business purposes or for non-commercial or personal use." — [LICENSE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE.md) +- The only tamper clause: "You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software." The word governed is "notices". — [LICENSE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE.md) +- ELv2, the model, separately forbids altering "license key functionality" and removing "functionality ... protected by the license key". The SUL has no such sentence. — [Elastic License 2.0](https://spdx.org/licenses/Elastic-2.0.html) +- **n8n FAQ, "What you cannot do under the community license" (verbatim list):** "Host n8n as a service and allow your clients to build workflows"; "Allow external end users to build or configure their own workflows through your product, whether via a custom UI, our API, MCP, or an AI agent acting on the user's behalf."; "Fork n8n's code to launch your own automation product"; "White-label n8n by removing our branding and offering n8n as is."; "Use enterprise features that ask for a license key without an Enterprise license." — [n8n License FAQ](https://docs.n8n.io/n8n-community-license/community-license/license-faq) +- The FAQ also states n8n's test: "The Sustainable Use License restricts use where the commercial value of a product derives entirely or substantially from n8n functionality." — [n8n License FAQ](https://docs.n8n.io/n8n-community-license/community-license/license-faq) +- In its 2025 DMCA notice n8n wrote that the targeted fork "made all our paid Enterprise features freely available, which is obviously not allowed, as that code has a different license". That frames the violation around *Enterprise-licensed code*, not around changes to gating as such. — [GitHub DMCA 2025-05-27-n8n-io](https://github.com/github/dmca/blob/master/2025/05/2025-05-27-n8n-io.md) +- The modification-notice duty also applies: modified copies must carry "a prominent notice stating that you have modified the software". — [LICENSE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE.md) + +### Inferences +- **Three scenarios, by risk:** + 1. *Make existing Enterprise-licensed code run without a license* (the approach of the "unlocker" forks, not named here). This is clearly unlicensed use of Enterprise code in production. It is copyright infringement and/or breach, and it is the pattern n8n has already taken down via DMCA. **High risk.** + 2. *Delete all Enterprise-licensed code, write original replacements, run internally* (the approach the sreent/"tuflow" fork claims). The SUL text appears to allow this: modification for internal use, and no license-key clause. The counter-arguments are (i) n8n's FAQ interpretation, (ii) the notice clause, if a court read "licensing ... notices" broadly to include in-product "upgrade to Enterprise" UI or plan banners, which is a stretch, and (iii) the claim that the overall fork is "your own automation product". **Moderate/uncertain risk; defensible on the text.** Keep all copyright and licensing notices and add the modification notice. + 3. *Distribute or sell scenario 2 to third parties, or host it for customers.* This breaches "distribute ... only if you do so free of charge for non-commercial purposes" and the internal-use limit, whatever the gating question. Free non-commercial distribution of the fork's SUL portions is allowed but must carry the SUL terms. The new original code can carry any license, but a combined fork is still bound by the SUL for the n8n parts. **High risk if commercial.** +- **Plugin route:** a plugin (e.g. a community node) that only adds new nodes or features in its own code is outside the gating question. A plugin whose purpose is to make Enterprise-licensed code run without a license falls into scenario 1, and n8n could argue contributory or inducement liability even though the plugin itself contains no n8n code. +- An FAQ is not part of the license ("No Other Rights" cuts both ways). Under both US and German contract principles, n8n's published interpretation would at most be evidence of intent, and ambiguities are typically construed against the drafter. Under German AGB law (§305c(2) BGB) unclear standard terms are construed against the user of the terms, meaning the drafter. That provision comes from my own knowledge and was not verified in this session. + +### Gaps +- No court, regulator or n8n statement directly addresses scenario 2. +- I found no record of n8n contacting sreent/n8n or similar "rebuilt" forks. + +--- + +## 4. Is the SUL OSI open source? History, fair-code, commercial-use restrictions + +### Takeaway +No. n8n itself says it is not open source because of the use restrictions, and calls the model "fair-code". The project moved from Apache 2.0 + Commons Clause to the SUL on 17 March 2022, and added the Enterprise License in August 2022. Hosting n8n for others to build workflows, embedding a workflow builder for end users, white-labeling, and forking to launch a competing automation product are all prohibited without a commercial agreement. Consulting, building workflows for clients, and backend-only embedding are allowed. + +### Cited Findings +- "Although n8n's source code is available under the Sustainable Use License, according to the Open Source Initiative (OSI), open source licenses can't include limitations on use, so we do not call ourselves open source." — [n8n docs: Sustainable Use License](https://docs.n8n.io/n8n-community-license/sustainable-use-license) +- "The Sustainable Use License is a fair-code software license created by n8n in 2022." n8n "coined the term 'fair-code'". Fair-code describes software that "Is generally free to use and can be distributed by anybody", "Has its source code openly available", "Can be extended by anybody", and "Is commercially restricted by its authors." — [n8n docs](https://docs.n8n.io/n8n-community-license/sustainable-use-license); [faircode.io](https://faircode.io/) +- "n8n was licensed under Apache 2.0 with Commons Clause until 17 March 2022." The change tightened use to "internal business purposes" (previously Commons Clause restricted "sell") and lifted the ban on paid consulting and support. — [n8n docs](https://docs.n8n.io/n8n-community-license/sustainable-use-license); [n8n forum: A new license for n8n](https://community.n8n.io/t/a-new-license-for-n8n/11873); [GitHub issue #2932](https://github.com/n8n-io/n8n/issues/2932) +- Contributors sign a CLA that "gives n8n the ability to change its license without seeking additional permission." — [n8n docs](https://docs.n8n.io/n8n-community-license/sustainable-use-license) +- **Allowed (FAQ):** use to run your business; personal, learning and research use; "Build automations for your clients on your instance, as long as your clients do not have the possibility to create or edit them"; charge for workflow creation, consulting and training; "Use n8n behind the scenes in your own product, where users can use and trigger the automations you built, and even connect their own accounts"; run several instances. Managing n8n on a client's own server is allowed "as long as you don't offer hosting as well". — [n8n License FAQ](https://docs.n8n.io/n8n-community-license/community-license/license-faq) +- **Prohibited (FAQ):** an embedded workflow builder, even with custom UI ("The SUL test is not about UI visibility — it is about who controls the workflow logic"); "Automation-as-a-service". — [n8n License FAQ](https://docs.n8n.io/n8n-community-license/community-license/license-faq) +- Commercial users must "sign a separate commercial agreement with us" (license@n8n.io). — [n8n docs](https://docs.n8n.io/n8n-community-license/sustainable-use-license) +- Competitor commentary (with a commercial interest) frames n8n as "source-available" rather than open source. — [Activepieces blog](https://www.activepieces.com/blog/n8n-license-fair-code-community-enterprise-2026); [Sim.ai](https://www.sim.ai/library/apache-2-0-vs-fair-code) + +### Inferences +- Since the CLA lets n8n relicense, future license versions could add an ELv2-style license-key clause. A fork that relies on today's text should pin to a specific version. Licenses already granted for past versions generally cannot be revoked retroactively, beyond the license's own termination mechanism. + +### Gaps +- I could not retrieve the original n8n blog post (n8n.io/blog/announcing-new-sustainable-use-license/) directly. Only the docs, the forum and a third-party summary were seen. +- I found no Hacker News thread in this session's searches. Community sentiment is therefore not documented here. + +--- + +## 5. Clean-room reimplementation: copyright, contract, DMCA §1201 (US vs EU) + +### Takeaway +Copyright protects code expression, not features, functionality, ideas or (in the EU) interfaces' underlying ideas. An independently written product that reproduces n8n's enterprise *features* (SSO, RBAC, Git environments, log streaming, external secrets) is on strong copyright ground in both the US and the EU, especially with documented clean-room separation. The main residual risks are three. (1) **Contract:** if you are a SUL licensee, US courts (Bowers v. Baystate) may enforce license terms beyond what copyright requires, while the EU voids contract terms that override interoperability and study rights. (2) **Infringement via scope conditions:** acts outside the SUL's limits are "not licensed" (MDY v. Blizzard condition/covenant analysis). (3) **DMCA §1201:** this is weak for n8n, because n8n itself disclaimed having technological measures in its DMCA notice. + +### Cited Findings +- **Google v. Oracle (US S. Ct., 5 April 2021, 6–2):** Google's reimplementation of ~11,500 lines of Java SE "declaring code" from 37 API packages was fair use as a matter of law. The Court *assumed without deciding* that the code was copyrightable. Commentators read the holding as narrow and fact-specific ("reimplementation of a user interface"). — [Dorsey & Whitney](https://www.dorsey.com/newsresources/blogs/tmca/2021/04/google-v-oracle-scotus-sides-with-google-on-fair-u); [Jenner & Block](https://www.jenner.com/en/news-insights/publications/client-alert-us-supreme-court-holds-that-copying-declaring-code-is-fair-use) +- **SAS Institute v. World Programming (CJEU C-406/10, 2 May 2012):** "the functionality of a computer program, including the programming language and the format of data files, constitute the overarching ideas behind a program ... and so are not protected by copyright". A lawful licensee may "observe, study or test the program functions to determine the underlying ideas and principles". Manuals can still be protected as literary works. — [Fieldfisher](https://www.fieldfisher.com/en/insights/sas-institute-inc-v-world-programming-limited); [IPKat](https://ipkitten.blogspot.com/2011/11/advocate-general-says-forget.html) +- **EU Software Directive 2009/24/EC.** These provisions are quoted from my own knowledge of the text; automated retrieval from EUR-Lex failed in this session, so verify against [EUR-Lex 32009L0024](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32009L0024): + - Art. 1(2): ideas and principles underlying any element of a program, "including those which underlie its interfaces", are not protected. + - Art. 5(3): the right to observe, study and test while running the program. + - Art. 6: decompilation permitted when indispensable for the interoperability of an independently created program. + - Art. 8(2): contractual provisions contrary to Art. 6 or Art. 5(2)–(3) "shall be null and void". + - Art. 7(1)(c): Member States must provide remedies against circulating means whose sole intended purpose is to remove or circumvent technical protection of programs. + - A secondary source confirms the Directive's interoperability reverse-engineering right "cannot be waived contractually". — [Wikipedia: Bowers v. Baystate](https://en.wikipedia.org/wiki/Bowers_v._Baystate_Technologies,_Inc.) +- **Bowers v. Baystate (Fed. Cir. 2003):** a shrinkwrap license clause prohibiting reverse engineering was enforced and *not* preempted by the Copyright Act. It is criticized as letting contracts override fair use. — [Wikipedia](https://en.wikipedia.org/wiki/Bowers_v._Baystate_Technologies,_Inc.); [WilmerHale](https://www.wilmerhale.com/insights/publications/shrink-wrap-licenses-and-reverse-engineering-april-16-2003) +- **MDY v. Blizzard (9th Cir. 2010, 629 F.3d 928):** + - A licensee's breach is copyright infringement only if the violated term is a *condition* (limits the license's scope) with a nexus to the exclusive rights. Breach of a mere *covenant* is only a contract claim. + - Separately, §1201(a)(2) liability "does not require a nexus between circumvention and actual copyright infringement". + - Blizzard's Warden anti-bot system was held an access control as to certain dynamic elements. + - [InfoLawGroup](https://www.infolawgroup.com/insights/2010/12/articles/copyright/ninth-circuit-highlights-the-importance-of-welldrafted-software-licenses-and-terms-of-use); [Vondran Legal](https://www.vondranlegal.com/copyright-case-briefs-mdy-industries-llc-v-blizzard-entertainment-inc); [CITP Princeton](https://blog.citp.princeton.edu/?p=6556) +- **n8n disclaimed TPMs:** in its 2025 DMCA notice to GitHub, to the question "Do you claim to have any technological measures in place to control access to your copyrighted content?", n8n answered "No". — [GitHub DMCA 2025-05-27-n8n-io](https://github.com/github/dmca/blob/master/2025/05/2025-05-27-n8n-io.md) +- **GitHub's own policy** separately prohibits "sharing unauthorized product licensing keys, software for generating unauthorized product licensing keys, and/or software for bypassing checks for product licensing keys". It has applied this to KeyAuth bypass repos and, in 2019, to a GitLab EE license-key generator. — [GitHub DMCA repo / transparency](https://github.com/github/dmca); [GitHub DMCA takedown policy](https://docs.github.com/en/site-policy/content-removal-policies/dmca-takedown-policy) +- **Clean-room practice** (general; from my own knowledge, not sourced in this session). Typical controls: + - A "dirty" spec team writes a functional spec from public docs and black-box observation. + - A legal reviewer scrubs the spec of code expression. + - A "clean" team that has never seen the target source implements from the spec. + - Everything is documented (access logs, attestations, spec versions). + - Classic US references are Phoenix Technologies' IBM BIOS clone and *Sony v. Connectix* / *Sega v. Accolade* (intermediate copying for interoperability as fair use). These cases are not verified here. + +### Inferences +- **Independent product (no n8n code at all):** copyright risk is low in both jurisdictions if the code is original. Features, workflow concepts, and compatibility with n8n's workflow-JSON format are ideas or functionality (SAS; Google v. Oracle by analogy). The SUL does not bind someone who never "uses" n8n. Watch for: copying UI text, docs or manual prose, icons or node descriptions (protectable expression); trademark (§6); patents (none found in this research, but not searched); and team contamination from reading n8n source. +- **Contract binding:** the SUL's "By using the software, you agree" makes it a contract as well as a license for anyone who runs n8n. In the US, under Bowers, contract terms can restrict conduct copyright alone would allow. But the SUL's terms do *not* prohibit independent reimplementation or studying the software, so there is no term to breach by building an independent product. Inside a fork, the relevant terms are the use and distribution limits. +- **EU:** even if n8n tried to restrict observation or study, Art. 8 voids contract terms contrary to Art. 5(3) and Art. 6. A clean-room team in the EU can lawfully study n8n's *running* behaviour as a licensee. Decompilation-type acts are limited to interoperability. +- **Condition vs covenant applied to the SUL:** the termination clause ("such use is not licensed") and the "only for" phrasing make the internal-use and free-distribution limits look like scope *conditions*. Commercial hosting or resale of a fork is therefore likely copyright infringement in the US, not just breach. +- **DMCA §1201 (US):** several facts weaken a §1201 claim by n8n: + - n8n's "No" answer in its own DMCA notice. + - The source is published, and the SUL permits modification. + - The Federal Circuit's *Chamberlain v. Skylink* (2004) requires a nexus to infringement (my own knowledge; this contrasts with the 9th Circuit's MDY rule, so the circuit matters). + - §1201(f) exempts circumvention for interoperability of independently created programs (also my own knowledge). + A §1201 risk remains mainly for *distributing tools* that bypass license checks to enable Enterprise-licensed code. GitHub's platform policy may remove such repos even without a strong §1201 claim. An independent product that never touches n8n's license check is outside this question. +- **EU anti-circumvention:** for software, Directive 2009/24 Art. 7(1)(c) applies rather than InfoSoc Art. 6 (which excludes programs, per my own knowledge, unverified). It targets means whose *sole intended purpose* is circumvention. A standalone "unlocker" plainly has that purpose. + +### Gaps +- I could not retrieve primary text of the EU Directive or the court opinions in this session. Quotations are from secondary summaries or flagged as from memory. +- There is no case law on whether a license-key check in source-available, modifiable software is an "effective" technological measure. +- No patent search was conducted on n8n GmbH. + +--- + +## 6. Trademark: using "n8n" in a fork or compatible product + +### Takeaway +The SUL grants no trademark rights ("Any use of the licensor's trademarks is subject to applicable law"). n8n has a US application for "N8N" and has cited its name in a takedown (the targeted fork "used our name"). A fork or compatible product should use its own name and branding. At most it should use nominative wording such as "compatible with n8n workflows", with a non-affiliation disclaimer. Note the tension: the SUL forbids removing *notices*, while the FAQ forbids white-labeling only when "offering n8n as is". Rebranding the UI while keeping copyright and license notices appears consistent with both (the sreent/"tuflow" fork claims to do this). + +### Cited Findings +- SUL: "Any use of the licensor's trademarks is subject to applicable law." — [LICENSE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE.md) +- US trademark application for standard-character "N8N", filed 2021-09-14 (status shown on the Justia record at its last update; verify current status at USPTO). — [Justia Trademarks](https://trademark.justia.com/970/27/n8n-97027061.html) +- n8n's DMCA notice: "They forked our repository, used our name ... So this is actually a case of IP + Copyright". — [GitHub DMCA 2025-05-27-n8n-io](https://github.com/github/dmca/blob/master/2025/05/2025-05-27-n8n-io.md) +- FAQ prohibits "White-label n8n by removing our branding and offering n8n as is." — [n8n License FAQ](https://docs.n8n.io/n8n-community-license/community-license/license-faq) +- The sreent fork says it rebrands as "tuflow" across the editor, server pages and emails (per its README; not to be read by STaurtomation contributors beyond this summary). + +### Inferences +- In both the US (nominative fair use) and the EU (EUTMR Art. 14(1)(c), referential use "in accordance with honest practices"; my own knowledge), describing compatibility is generally allowed. Using "n8n" in a product name, logo or domain invites a likelihood-of-confusion claim. + +### Gaps +- I could not find an official n8n trademark or brand-usage policy page. EU and German (DPMA/EUIPO) registrations for "n8n" were not checked. + +--- + +## 7. Precedents: forks and unlockers, n8n's enforcement, official position + +### Takeaway +Several GitHub repos openly "unlock" n8n enterprise features while redistributing n8n's Enterprise-licensed code. They are deliberately not named or linked here. n8n has used a DMCA takedown against at least one, in May 2025, and that GitHub repo is now gone. Others remained live as of October 2026. A newer pattern (sreent/n8n, autumn 2026) claims to delete all Enterprise-licensed code, rebuild the features, and stay internal-use-only. I found no n8n response to it. + +### Cited Findings +- **May 2025 takedown:** n8n's DMCA notice of 2025-05-27 targeted a fork's GitHub repository, claimed "The entire repository is infringing", covered "Both" GitHub and npm, answered "No" on technological measures, and requested "Reported content must be removed". — [GitHub DMCA 2025-05-27-n8n-io](https://github.com/github/dmca/blob/master/2025/05/2025-05-27-n8n-io.md) + - The GitHub repo was gone when checked on 2026-10-29. The associated npm package was nevertheless still being published as of September 2026. +- The other n8n-tagged entries in GitHub's DMCA repo (2025-08-13 "n8n" workflow-template notice against 9,225 forks of a workflow-template collection; 2026-03-18 counter-notice; 2026-09-29 Viver de IA) are third-party disputes over workflow JSON or templates, not n8n GmbH enforcing its license. — [2025-08-13-n8n](https://github.com/github/dmca/blob/master/2025/08/2025-08-13-n8n.md); [2026-03-18 counternotice](https://github.com/github/dmca/blob/master/2026/03/2026-03-18-n8n-counternotice.md) +- **Other unlocker forks:** several remained live as of 2026-10-29, some shipping Docker images. They redistribute n8n's Enterprise code and are outside the Enterprise License. Not named here by policy. +- **Rebuild-style fork (prior art only; do not read or copy its code):** + - sreent/n8n (created 2026-09-30, 0 stars) says it is "for internal business use only", rebranded "tuflow", and "has no enterprise code of n8n. It has its own versions of the enterprise features". + - Claimed rebuilt features: sharing, projects and roles, OIDC/SAML/LDAP, external secrets, Git source control, variables, log streaming, S3/Azure binary data, multi-main, and more. + - These are the fork's own claims; nobody audited the code for actual clean-room provenance. Because it is a modified n8n codebase, it is n8n source for STaurtomation's purposes. +- **Official n8n position:** "Use enterprise features that ask for a license key without an Enterprise license" and "Fork n8n's code to launch your own automation product" are listed as not allowed. — [n8n License FAQ](https://docs.n8n.io/n8n-community-license/community-license/license-faq) + +### Inferences +- Enforcement so far is selective and platform-based (a GitHub DMCA against an *n8n-named*, publicly distributed, npm-published unlocker). Unlockers persisting suggests n8n has not swept them all, or that GitHub has not acted. The npm package surviving despite a notice that named npm is notable but unexplained. +- The takedown case combined the three highest-risk factors: n8n's name, redistribution of Enterprise-licensed code, and public package distribution. An independent, differently named product avoids all three. + +### Gaps +- I found no Reddit or community-forum threads with n8n staff statements on unlockers, and no evidence of lawsuits. +- Whether n8n sent private cease-and-desist letters is unknown. + +--- + +## 8. Comparable source-available cases + +### Takeaway +The successful "escapes" from source-available relicensing (OpenSearch, OpenTofu, Valkey) all forked the *last permissively licensed version*, not a source-available one. n8n has no such base: its pre-2022 code was Apache 2.0 *plus Commons Clause*, which is still commercially restricted. Another lesson: copyright accusations over reimplemented features happen in practice (HashiCorp vs OpenTofu, 2024), so clean-room documentation matters. + +### Cited Findings +- **Elastic → OpenSearch:** AWS forked Elasticsearch/Kibana 7.10 (the last Apache 2.0 versions) in 2021. Governance later moved to the OpenSearch Software Foundation (Linux Foundation). Elastic added AGPL as an option in 2024 (8.16.0). ELv2 explicitly bans license-key circumvention and hosted-service offering. — [dev.to/AWS builders](https://dev.to/aws-builders/turning-license-changes-into-opportunity-1n35); [LeMondeInformatique](https://www.lemondeinformatique.fr/actualites/lire-le-retour-d-elastic-a-l-open-source-orthodoxe-94602.html); [Elastic-2.0 SPDX](https://spdx.org/licenses/Elastic-2.0.html) +- **HashiCorp → OpenTofu:** HashiCorp moved from MPL 2.0 to BSL in August 2023. On 3 April 2024 Wilson Sonsini sent OpenTofu a cease-and-desist alleging that BSL code was copied into OpenTofu's `removed` block implementation, and reserved DMCA and litigation rights. OpenTofu responded that the code derived from older MPL-2.0 code and that HashiCorp had copied the same code itself. — [OpenTofu blog](https://opentofu.org/blog/our-response-to-hashicorps-cease-and-desist/); [The New Stack](https://thenewstack.io/opentofu-project-denies-hashicorps-allegations-of-code-theft/) +- **Redis → Valkey:** Redis moved from BSD to RSALv2/SSPLv1 in March 2024. The Linux Foundation, AWS, Google, Oracle, Ericsson and others forked Redis 7.2.4 as BSD-licensed Valkey. Redis 8 added AGPLv3 in May 2025. — [The Register](https://www.theregister.com/2025/05/01/redis_returns_to_open_source/); [The Stack](https://www.thestack.technology/redis-reverts-to-open-source/) +- **Sentry FSL:** FSL-1.1 permits any "Permitted Purpose" other than a "Competing Use" (making the software available "in a commercial product or service that ... substitutes for the Software"). Each release "irrevocably" becomes Apache 2.0 (or MIT) "on the second anniversary". — [FSL template (getsentry/fsl.software)](https://github.com/getsentry/fsl.software); [fsl.software](https://fsl.software/) +- **GitLab EE:** GitHub processed a 2019 DMCA against a repo generating GitLab EE license keys, describing it as a "circumvention-tool". — [GitHub DMCA repo](https://github.com/github/dmca) (as reported via a DMCA mirror in search results; I did not open the original notice) + +### Inferences +- Unlike FSL or BSL, the SUL and the EE license have no time-delayed conversion to open source. Old n8n code never becomes free for commercial reuse. +- For a commercial competitor, the OpenTofu/Valkey model (fork a permissive base) is unavailable. The realistic path is an *independent* codebase, perhaps with workflow-format compatibility, or a fork confined to internal or non-commercial use. + +### Gaps +- The outcome of the HashiCorp–OpenTofu dispute after April 2024 (including the IBM acquisition context) was not researched. +- I found no case of a fully clean-room reimplementation of a *specific* source-available product's gated features being litigated. + +--- + +## 9. Community Edition vs paid tiers (2025–2026), including the free "Registered" unlocks + +### Takeaway +Self-hosted n8n has four editions: Community, Registered Community (free, email registration), Business, and Enterprise. Without a key the Community edition lacks: +- custom variables +- environments and Git version control +- external secrets +- external binary storage +- log streaming +- multi-main +- projects +- SSO (SAML, LDAP) +- workflow and credential sharing + +A free registration key unlocks folders, debug in editor and custom execution data (save, find and annotate execution metadata). Per-plan pricing detail is in [n8n-feature-feasibility.md](n8n-feature-feasibility.md). + +### Cited Findings +- "Every self-hosted installation runs on the same underlying product." The Community edition "is what n8n runs without a license key"; Registered Community is "extra features unlocked by registering your email. Still free"; the Business and Enterprise plans get "a license key that unlocks the features for that plan." — [n8n docs: Compare editions](https://docs.n8n.io/deploy/host-n8n/community-edition-features/) +- **Community edition excludes:** Custom variables; Environments; External secrets; External storage for binary data; Log streaming (Logging *is* included); Multi-main mode (Queue mode *is* included); Projects; SSO (SAML, LDAP); Sharing (workflows, credentials); Version control using Git. — [n8n docs: Compare editions](https://docs.n8n.io/deploy/host-n8n/community-edition-features/) +- **Registered Community unlocks:** "Folders", "Debug in editor: Copy and pin execution data when working on a workflow", "Custom execution data: Save, find, and annotate execution metadata". Registration is via Settings > Usage and plan > Unlock > "Send me a free license key". — [n8n docs: Compare editions](https://docs.n8n.io/deploy/host-n8n/community-edition-features/) +- Third-party summaries say some doc versions listed one day of workflow history among registered unlocks, and that the registered license "will not expire". I could not confirm either on the current page. — [nordflux.de](https://nordflux.de/en/guides/what-the-n8n-community-edition-cannot-do-free-features-via-registration-key) +- n8n states "The pricing page is the source of truth. Exact features per plan and edition can change." — [n8n docs](https://docs.n8n.io/deploy/host-n8n/community-edition-features/) +- Users have reported registered features not appearing in the UI despite "Registered" status. — [n8n community forum](https://community.n8n.io/t/folders-license-features-not-appearing-despite-registered-status-windows-docker-self-hosted/301124) + +### Inferences +- Features unlocked by the free registration key are still *license-key gated*. Under n8n's FAQ reading, bypassing them is equally "using enterprise features that ask for a license key", although n8n gives them away for free, which makes harm or damages minimal. + +### Gaps +- The current n8n pricing page was not fetched in this part of the research (see [n8n-feature-feasibility.md](n8n-feature-feasibility.md), which did fetch it). Treat tier allocations as subject to change. diff --git a/docs/research/notes/windmill.md b/docs/research/notes/windmill.md new file mode 100644 index 0000000..dc986fe --- /dev/null +++ b/docs/research/notes/windmill.md @@ -0,0 +1,251 @@ +> Ported from earlier research (2026-10-29) and sanitized for clean-room use: source-code-derived details removed. Not legal advice. + +# Windmill (windmill-labs/windmill) as a self-hosted n8n alternative, as of late October 2026 + +Research date: 2026-10-29. "Verified" means read directly from a primary source on that date: the windmill.dev pricing or docs page, or the GitHub repo and API. Vendor marketing claims are labeled as vendor claims. Third-party aggregators are labeled as such. + +## 1. License: exact terms, Enterprise Edition (EE) scope, changes from 2023 to 2026 + +### Takeaway +Windmill has an open-core, split license. The source in `backend/` and `frontend/` is AGPLv3. API clients and the OpenAPI/OpenFlow spec are Apache-2.0. Code behind the `enterprise` compile flag, and frontend code that needs a positive license check, is proprietary. The prebuilt "Community Edition" (CE) Docker images are not pure AGPL: they contain proprietary, non-public code under a freeware-style grant. You may use them free internally, but you may not sell, resell, modify, wrap, or offer them as a managed service. The proprietary carve-out first appeared in September 2023. The CE-binary terms were spelled out in March 2025. White-labeling and embedding restrictions were added to the LICENSE file in October 2026. + +### Cited Findings +- LICENSE (verbatim): "Source code in this repository is variously licensed under the Apache License Version 2.0 (see file ./LICENSE-APACHE), or the AGPLv3 License (see file ./LICENSE-AGPL) and a proprietary license for certain enterprise features." The repo root contains LICENSE, LICENSE-AGPL, LICENSE-APACHE, and NOTICE. GitHub's SPDX field reports "NOASSERTION". — [LICENSE file, windmill-labs/windmill](https://github.com/windmill-labs/windmill); verified via the GitHub API on 2026-10-29. +- "The files under backend/ are AGPLv3 Licensed, except any snippets of code under the compile flag 'enterprise'. Those snippets and files are under a proprietary and commercial license. The files under frontend/ are AGPLv3 Licensed, except any snippets of code that require a positive license check to be activated... Private and public forks MUST not include any of the above proprietary and commercial code." — [LICENSE file, windmill-labs/windmill](https://github.com/windmill-labs/windmill) +- Apache-2.0 covers `python-client/`, `deno-client/`, `go-client/`, `powershell-client/`, and "the openapi files, including the OpenFlow spec". — [LICENSE file, windmill-labs/windmill](https://github.com/windmill-labs/windmill) +- "The binary compilable from source code in this repository without the 'enterprise' feature flag is open-source under the AGPLv3 License." — [LICENSE file, windmill-labs/windmill](https://github.com/windmill-labs/windmill) +- On the CE images: "The 'Community Edition' of Windmill available in the docker images hosted under ghcr.io/windmill-labs/windmill and the github binary releases contains the files under the AGPLv3 and Apache 2 sources but also includes proprietary and non-public code and features which are not open source... Windmill Labs, Inc. grants a right to use all the features of the 'Community Edition' for free without restrictions other than the limits and quotas set in the software and a right to distribute the community edition as is but not to sell, resell, serve as a managed service, modify or wrap under any form without an explicit agreement." — [LICENSE file, windmill-labs/windmill](https://github.com/windmill-labs/windmill) +- "To use Windmill 'Community Edition' as is internally in your organization, or to use its APIs as is, you do NOT need a commercial license." Re-exposing Windmill parts to your own users (white-labeling) needs a commercial license, except for iframed public apps. So does building a commercially sold feature on CE or embedding CE in a distributed product. — [LICENSE file, windmill-labs/windmill](https://github.com/windmill-labs/windmill) +- EE is unlocked by a `LICENSE_KEY` entered in instance settings. One key can be used on multiple instances, and dev instances should set the "Non-prod instance" flag. The Helm chart uses a different EE image (`windmill-ee`) when `enterprise.enabled: true`. — [Self-host docs](https://www.windmill.dev/docs/advanced/self_host); [README](https://github.com/windmill-labs/windmill) +- License history, taken from the commit history of the LICENSE file (verified via the GitHub API): + - 2022-05-05: first commit. Backend and frontend were AGPL, and `python-client/` and `community/` were Apache-2.0. + - 2023-03-01: the Apache scope was extended to the deno and go clients and the OpenAPI/OpenFlow spec. + - 2023-09-11: this is the key change. The proprietary carve-out was added for `enterprise`-flagged backend code and license-checked frontend code, together with the clause "Private and public forks MUST not include" that code. + - 2024-04-18: the PowerShell client was added to the Apache scope. + - 2025-03-07: the header now names "a proprietary license for certain enterprise features". The explicit CE-binary terms were added (proprietary, non-public code, no reselling, managed service, modifying, or wrapping), along with the AGPL statement for binaries built without the flag. The earlier sentence offering "tools to clean the codebase from those snippets upon demand" was removed. + - 2026-10-25: the white-labeling and embedding commercial-license paragraph and the "internal use does NOT need a commercial license" paragraph were added to LICENSE. The commit message reads "trim env vars and license" from the README, which suggests the text moved from the README into LICENSE. — [LICENSE commit history](https://github.com/windmill-labs/windmill/commits/main/LICENSE) +- A third-party view: "the AGPL license is stricter than n8n's fair-code: any modifications served over a network must be open-sourced." — [automationatlas.io](https://automationatlas.io/guides/n8n-vs-windmill-2026-comparison/) +- Windmill's own comparison page calls Windmill "AGPLv3 (true OSS)" and n8n's Sustainable Use License "source-available, not OSS". — [windmill.dev/compare/n8n](https://www.windmill.dev/compare/n8n) (vendor claim) + +### Inferences +- The "true OSS" marketing applies only to a self-built binary without the enterprise flag. The official CE images, which are what most self-hosters run, include proprietary code and carry no-modify and no-managed-service terms. That puts their practical freedom closer to "free-to-use freeware on an AGPL core". For internal use in place of n8n this barely matters. It matters a lot for MSPs and SaaS embedding: offering Windmill CE to clients as a hosted service needs a commercial agreement, much like n8n's SUL. +- I found no relicensing away from AGPL, unlike the moves of HashiCorp or n8n. The changes were additive carve-outs that tightened terms on the binary and the proprietary code. +- Which CE limits a pure AGPL build enforces, compared with the official CE image, is not documented. Per the LICENSE text, a self-built AGPL binary would be legally modifiable, and the LICENSE says enterprise-flagged code is proprietary and must not be included in forks. + +### Gaps +- I did not verify whether the AGPL build without the enterprise flag has the same quotas as the CE image (50 users, 10 SSO users, 3 workspaces), or whether those quotas can be legally patched out under AGPL. +- I found no public EE license text or EULA. + +## 2. Plans and pricing: CE vs. Enterprise/Cloud, exact CE limits + +### Takeaway +The self-hosted CE is $0 with unlimited executions. Its limits are 50 users max, 10 SSO users, 3 workspaces, 4 groups, git sync for up to 2 users, job retention of 30 days or less, 100 email triggers per day, and 10 GiB of object storage. Enterprise starts at $120/mo. It is priced at $20/mo per builder seat, $10/mo per non-builder (half a seat), and about $50/mo per compute unit (CU = 2 worker-GB-month). Nonprofits and universities get 40% off. A "Pro" variant exists for very small companies and seed-stage startups. + +### Cited Findings +- The pricing page lists "Free and Open-source": $0/mo, self-hosted, unlimited executions, community support on Discord. "Enterprise": "from $120/mo", with Pro, Nonprofit, and Enterprise variants. — [Pricing](https://www.windmill.dev/pricing) (verified 2026-10-29) +- Unit prices: Builder seat $20/mo, where a builder writes code, builds flows or apps, or is a workspace admin. Non-builder or external JWT user: $10/mo (half a seat). One compute unit = 2 worker-GB-month. A 2 GB worker is 1 CU, self-hosted workers above 2 GB count as 2 CU, and native workers count as 1 CU. Totals round up to a whole CU. The page's worked example: 2 standard workers ($100) + 8 native subworkers ($50) + 1 builder ($20) = $170/mo, which implies about $50 per CU. — [Pricing](https://www.windmill.dev/pricing) +- Guests: the first 100 distinct guest emails per 30 days are free. Beyond that, 4 guests count as 1 seat. Guests are not available on the cloud Free and Team plans. — [Pricing](https://www.windmill.dev/pricing) +- Pro tier: self-hosted only, for individuals, businesses under 10 employees and $250k revenue, and seed-stage startups. — [Pricing](https://www.windmill.dev/pricing) +- Nonprofits and universities get the regular Enterprise plan at a 40% discount. — [Pricing](https://www.windmill.dev/pricing) +- CE limits from the pricing table: + + | Limit | CE value | + |---|---| + | Workspaces | 3 | + | Users | 50 max | + | Groups | 4 max | + | SSO users | 10 | + | Git sync | up to 2 users | + | Job run retention | 30 days or less | + | Email triggers | 100/day | + | Object storage | 10 GiB | + | Workspace forks and dev workspaces | count toward the 3-workspace limit | + + — [Pricing](https://www.windmill.dev/pricing) +- A cloud "Team" plan is mentioned as billed on actual usage, but the pricing page did not give its price. A third party reports Windmill Cloud Team at "roughly $10 per user per month with included compute credits" and Enterprise as "per-worker, custom-priced". That conflicts with the vendor page's $20 builder seat and may be stale. — [automationatlas.io](https://automationatlas.io/guides/n8n-vs-windmill-2026-comparison/) vs. [Pricing](https://www.windmill.dev/pricing) +- The self-host docs state no CE limit on worker count or native workers. — [Self-host docs](https://www.windmill.dev/docs/advanced/self_host) + +### Inferences +- A small self-hosted EE estimate, based on the pricing formula: 5 builders ($100) + 4 workers at 2 GB (4 CU, about $200) comes to about $300/mo. The real minimum is "from $120/mo". These are list prices; actual quotes may differ. +- For small teams, the binding CE limits are likely git sync (2 users), job retention (30 days), and audit logs (none). The 50-user and 10-SSO-user caps also matter for SSO-based setups. + +### Gaps +- The exact cloud Team price and its limits did not render on the pricing page. +- I could not date when the 50-user cap and 4-group cap were introduced. I recall CE once had more permissive user limits, but I did not verify this; treat it as unconfirmed. +- I did not find a published per-CU price; $50 is derived from the worked example. + +## 3. Feature gating (CE vs. EE) + +### Takeaway +CE includes RBAC basics: users, admins, developers, operators, folders, up to 4 groups, overriding default roles, and workspace secret encryption. It also has unlimited executions and horizontal worker scaling. EE gates most n8n-style enterprise items: SAML, SCIM, custom OIDC, uncapped SSO, audit logs, unlimited retention, external secret managers, git sync beyond 2 users, UI deployment between workspaces (staging to prod), Prometheus/OTel, autoscaling, worker group management UI, and multiplayer editing. Log streaming as such is not listed. The closest EE items are service logs to S3, OpenTelemetry, and an instance events webhook. + +### Cited Findings +Free vs. Enterprise, from the pricing page ([Pricing](https://www.windmill.dev/pricing), verified 2026-10-29): + +| Area | CE | EE | +|---|---|---| +| SSO users | 10 | uncapped, requires seats | +| SAML and SCIM with group sync | No | Yes | +| Custom OAuth / custom OIDC | No / No | Yes | +| Custom workspace roles | override default roles only | full | +| Service accounts | No | Yes | +| Users / groups / workspaces | 50 / 4 / 3 | unlimited | +| Audit logs | No | unlimited | +| Job run retention | 30 days or less | unlimited | +| Schedule and workspace error handlers | No | Yes | +| Queue metrics, Prometheus, OpenTelemetry | No | Yes | +| Git sync | up to 2 users | Yes | +| Deploy to staging/prod web UI | No | Yes | +| "Run on behalf of" across workspaces | No | Yes | +| Workspace forks / dev workspaces | count toward the 3-workspace limit | Yes | +| External secret backends (Vault, Azure KV, AWS SM) | No | Yes | +| Workspace secret custom encryption | Yes | Yes | +| Agent workers, SSH execution, Windows workers | No | Yes | +| Autoscaling | No | Yes | +| Worker group management UI | No | Yes | +| Concurrency limits, critical alerts, dedicated workers | No | Yes | +| Kafka, NATS, SQS, GCP Pub/Sub, Azure triggers | No | Yes | +| Email triggers | 100/day | unlimited | +| Object storage | 10 GiB | unlimited | +| Support and SOC 2 Type II report | community (Discord), no report | 24/7, 3-hour response, dedicated Slack channel, SOC 2 report | + +Other gating sources: +- Service logs on S3, OpenTelemetry tracing, and the instance events webhook are Enterprise-only. Log streaming and HA are not explicitly listed on the pricing page. — [Pricing](https://www.windmill.dev/pricing) +- Multiplayer (real-time collaborative editing) is available only on Cloud and self-hosted EE. — [Self-host docs](https://www.windmill.dev/docs/advanced/self_host) +- The server can be replicated for HA and workers replicated for throughput. Autoscaling is listed as an EE feature. — [Self-host docs](https://www.windmill.dev/docs/advanced/self_host) +- Windmill's comparison page also lists dedicated workers, external secret backends, and "extended audit retention" as EE-only. It says n8n gates source control and environments, SSO, custom roles, external secrets, audit logging, and log streaming behind Enterprise. — [windmill.dev/compare/n8n](https://www.windmill.dev/compare/n8n) (vendor claim) +- AI: only Anthropic Workload Identity Federation and AWS Bedrock OIDC role assumption are marked EE-only on the AI docs page. — [AI docs](https://www.windmill.dev/docs/core_concepts/ai_generation) + +### Inferences +- Versioning and history: scripts and flows have built-in version hashes and deployment history, which I believe is in CE. I did not verify this against a docs page in this session, so treat it as unconfirmed. Git sync, which is the git-backed version control, is the gated part. +- HA does not appear to be license-gated. Server and worker replicas run in CE because state lives in Postgres. Autoscaling and the worker-group UI are what EE adds. I base this on the self-host docs; I found no explicit "HA is CE" statement. +- Compared with n8n CE, Windmill CE is more generous on multi-user and RBAC: real users, folders, and 4 groups for free. It is roughly equal on SSO, where Windmill CE has 10 SSO users and n8n gates SSO entirely. It is similarly restrictive on audit logs, external secrets, and environments. + +### Gaps +- I did not fetch the plans_details docs page (it rendered empty), so finer CE/EE details could not be cross-checked, such as LDAP support and the granularity of folder permissions. +- LDAP is not mentioned anywhere I looked. + +## 4. Product model, triggers, integrations, AI + +### Takeaway +Windmill is a developer-first platform. Scripts are written in many languages and become endpoints, UIs, and cron jobs. Flows are DAGs of scripts built in a visual editor, as YAML, or as code. Apps can be full-code React or Svelte, or built in a legacy low-code drag-and-drop editor. Its integration catalog is small next to n8n's 1,600+ nodes: the vendor counts 50+ resource types plus the Hub, and Windmill instead relies on importing any npm or PyPI package. AI features are extensive and work with your own provider keys. + +### Cited Findings +- Script languages: "TypeScript, Python, Go, PHP, Bash, C#, SQL, Rust, Ruby and R, or any Docker image". — [Docs intro](https://www.windmill.dev/docs/intro) +- The README also lists GraphQL, PowerShell, Java, and Ansible. Bun is the default TypeScript runtime, with Deno and PHP on the `windmill-full` images, and Python uses uv. — [README](https://github.com/windmill-labs/windmill) +- Flows are an orchestrator for chaining scripts, with a visual editor, YAML, or workflows as code. Apps are full-code React or Svelte frontends plus a legacy low-code app editor. Data features include data tables, DuckDB, and DuckLake pipelines (alpha). — [Docs intro](https://www.windmill.dev/docs/intro) +- Target users: engineers who "write code, control what ships through review and promotion", and business teams who "build apps and automations with AI sessions". — [Docs intro](https://www.windmill.dev/docs/intro) +- Triggers: "Native triggers for HTTP, cron, Kafka, NATS, Postgres CDC, SQS, MQTT, SMTP and WebSocket". Every script also gets an HTTP endpoint and webhook URL. — [windmill.dev/compare/n8n](https://www.windmill.dev/compare/n8n) +- The pricing page adds GCP Pub/Sub and Azure triggers. Kafka, NATS, SQS, GCP, and Azure triggers are EE-only, and email triggers are capped at 100/day in CE. — [Pricing](https://www.windmill.dev/pricing) +- Integrations: the vendor says "50+ pre-built resource types" plus a community Hub with no stated count, and that any npm or PyPI package can be imported. It counts n8n at "1,600+ pre-built nodes". — [windmill.dev/compare/n8n](https://www.windmill.dev/compare/n8n) +- A third party says "100+ pre-built integrations and a Hub" and calls the catalog "smaller and closer to developer-leaning targets". — [automationatlas.io](https://automationatlas.io/guides/n8n-vs-windmill-2026-comparison/) +- The vendor page says n8n is better for non-developers on a visual canvas and is "the fastest path when the automation is a chain of mainstream SaaS calls". — [windmill.dev/compare/n8n](https://www.windmill.dev/compare/n8n) +- AI features: + - AI chat: navigates the app, edits workspace items, and inspects database schemas. + - AI sessions: full-page building with live preview and diff-and-deploy; enabled by default. + - Script copilot (Cmd/Ctrl+L); code completion requires Mistral Codestral. + - Flow copilot: builds flows step by step and suggests inputs, loop expressions, and branch predicates. + - AI app builder. + - AI form filling and cron generation. + - AI agent steps with provider selection and reasoning effort. + - MCP servers can be enabled in chat settings. + + — [AI docs](https://www.windmill.dev/docs/core_concepts/ai_generation) +- Supported AI providers, all bring-your-own-key: OpenAI, Azure OpenAI, Azure AI Foundry, Anthropic, Gemini and Anthropic on Vertex, Mistral Codestral, DeepSeek, Groq, OpenRouter, Together AI, AWS Bedrock, and any OpenAI-compatible endpoint, including Ollama. — [AI docs](https://www.windmill.dev/docs/core_concepts/ai_generation) +- The intro also lists AI agents, AI agent evals, MCP, and an AI sandbox. — [Docs intro](https://www.windmill.dev/docs/intro) + +### Inferences +- Windmill is not a drop-in no-code n8n replacement. It suits teams where most authors can write Python or TypeScript. AI sessions and copilots partly lower that barrier for business users. +- The integration gap is real for SaaS-glue use cases. For each SaaS connector an n8n user relies on, a Windmill user typically writes or imports a small script using the vendor's SDK. + +### Gaps +- I found no count of Hub scripts or integrations; hub.windmill.dev was not fetched. +- The dedicated triggers docs page rendered empty, so the trigger list comes from the compare and pricing pages. + +## 5. Tech stack and operations + +### Takeaway +Windmill has a Rust backend with stateless API servers and workers, a Svelte 5 frontend, and PostgreSQL as the only stateful dependency. Postgres also holds the job queue, so there is no Redis. It deploys with Docker Compose (Caddy, server, workers, native workers, LSP, and optional multiplayer) or the official Helm chart. The rule of thumb is about 1 worker per vCPU with 1-2 GB of RAM. + +### Cited Findings +- Stack: Rust backend, PostgreSQL (which also holds the job queue), Svelte 5 frontend, and sandboxing via nsjail and PID namespace isolation. — [README](https://github.com/windmill-labs/windmill) +- "Postgres holds the entire state of Windmill." Redis is not mentioned. — [Self-host docs](https://www.windmill.dev/docs/advanced/self_host) +- Compose ships `postgres:18`. A data volume from Postgres 16 or earlier blocks startup until you migrate or pin the version. Managed options: AWS Aurora, GCP Cloud SQL, Azure, Neon. — [Self-host docs](https://www.windmill.dev/docs/advanced/self_host) +- Compose services: db, windmill_server, windmill_worker (example: 3 replicas, each limited to 1 CPU and 2048M), windmill_worker_native (example: 2 replicas, each limited to 0.1 CPU and 128M), lsp, multiplayer, and caddy. — [Self-host docs](https://www.windmill.dev/docs/advanced/self_host) +- Helm: `helm repo add windmill https://windmill-labs.github.io/windmill-helm-charts/`. The chart is recommended for production. An S3-compatible global cache is recommended above 20 workers. — [Self-host docs](https://www.windmill.dev/docs/advanced/self_host) +- Rule of thumb: "1 worker per 1vCPU and 1-2 GB of RAM". — [Self-host docs](https://www.windmill.dev/docs/advanced/self_host) +- Performance, per the vendor: "~10ms cold starts", queue-based and horizontally scalable. — [windmill.dev/compare/n8n](https://www.windmill.dev/compare/n8n) +- A third party reports "sub-100ms cold-start overhead for hot workers". Teams "often end up with one worker pool per language", and worker sizing "matters more" than on n8n. For 5 engineers, it estimates about half a day of setup and half a day per quarter of maintenance, the same as n8n. — [automationatlas.io](https://automationatlas.io/guides/n8n-vs-windmill-2026-comparison/) + +### Inferences +- A minimal home or small-team instance needs Postgres, 1 server, and 1-2 workers. Based on the Compose resource limits, that probably fits in about 4 GB of RAM. I found no official minimum. +- With no Redis, the stack is ops-simpler than n8n in queue mode. However, it has more containers than single-process n8n: LSP, native workers, and Caddy. + +### Gaps +- I found no official minimum spec for the server and database, and no independent memory benchmarks. + +## 6. Community health + +### Takeaway +The project is very active: 18.3k stars, about 1.1k forks, and about 170 contributors. Releases come out almost daily; v1.853.1 shipped on 2026-10-29, with about 30 releases in October 2026 alone. The company is small and lightly funded: YC S22, Paris, 7 employees per YC, and a solo founder (Ruben Fiszel). Public funding data is sparse and conflicting. + +### Cited Findings +- GitHub API, 2026-10-29: 18,315 stars, 1,131 forks, 875 open issues, last push 2026-10-29, repo created 2022-05-05. The contributors endpoint paginates to 172, including anonymous contributors. — [GitHub repo](https://github.com/windmill-labs/windmill) +- Releases: v1.853.1 (2026-10-29), v1.853.0 (2026-10-28), v1.852.0 (2026-10-28), and so on. 30 releases between 2026-10-09 (v1.830.0) and 2026-10-29. — [GitHub releases](https://github.com/windmill-labs/windmill/releases) +- YC: Summer 2022 batch, founded 2022, team size 7, Paris, sole founder Ruben Fiszel (formerly distributed systems at Palantir). — [YC company page](https://www.ycombinator.com/companies/windmill) +- Funding conflicts between aggregators: CB Insights reports $500K over 3 rounds, with a convertible note that includes YC. Startups.fm reports a $5M total. Neither cites a press release. Several search hits for "Windmill" funding ($12M seed, $5M Series A) belong to unrelated companies: an AI performance-review startup and Windmill Air. — [CB Insights](https://www.cbinsights.com/company/windmill/financials); [startups.fm](https://startups.fm/startups/windmill-dev) + +### Inferences +- The release cadence is very fast, with several releases a day. That is good for velocity but implies frequent upgrades and possible churn. Operators should pin versions. +- The bus factor is a consideration: a solo founder and a small team, though the company is revenue-generating through EE and Cloud customers such as CFA Institute. + +### Gaps +- I found no verified funding round amounts or investor list beyond YC, and no confirmed current headcount beyond YC's listed 7, which may be stale. + +## 7. Migration from n8n + +### Takeaway +There is no importer. Windmill itself states: "No, there is no automated n8n-to-Windmill converter... Porting is a rewrite, not a conversion." The concept mapping is direct: workflows become flows, nodes become steps or scripts, and credentials become resources and variables. The effort depends on how much of each n8n workflow uses prebuilt SaaS nodes, which must become code. + +### Cited Findings +- "No, there is no automated n8n-to-Windmill converter." "Porting is a rewrite, not a conversion." — [windmill.dev/compare/n8n](https://www.windmill.dev/compare/n8n) +- Mapping, as inferred from the vendor page: + - An n8n JSON graph becomes a Windmill flow of scripts. + - Each node becomes a flow step or script. + - Code-node logic becomes regular scripts. + - Credentials become typed JSON "resources", and secrets become "variables". + - `{{ $json.field }}` expressions and connection topology must be reimplemented. + + — [windmill.dev/compare/n8n](https://www.windmill.dev/compare/n8n) +- The CFA Institute case study (vendor-published, January 2026): the SRE team evaluated Windmill for about a year and fully migrated off n8n in early 2025. "We were very quickly able to get our scripts out of n8n and transitioned over"; "only brief training sessions" were needed. Their reasons for leaving were wanting real programming capabilities and Git workflows. They run 25 synthetic tests every 5 minutes on Windmill Cloud EE. No workflow count or effort figure is given. — [CFA Institute case study](https://www.windmill.dev/case-studies/cfa-institute) +- n8n workflows can be exported as JSON via the CLI (`--backup` = `--all --pretty --separate`), but credential secrets stay encrypted in the n8n database. — [n8n CLI import/export](https://www.mintlify.com/n8n-io/n8n/cli/import-export) +- One third-party anecdote: Windmill's rollout took 9 days including SSO, against 3 days for n8n, for two UK clients. The author flags the small sample. — [automationatlas.io](https://automationatlas.io/guides/n8n-vs-windmill-2026-comparison/) + +### Inferences +- The effort is low for n8n workflows that are mostly Code or HTTP nodes, since they map to scripts almost 1:1. It is high for workflows built on many app nodes such as Gmail, Slack, or Sheets triggers, because each needs SDK code and app-specific polling triggers have no native equivalent. +- An AI-assisted route is plausible but unvalidated: feed the n8n JSON to Windmill's flow copilot or an external LLM to draft Windmill flow YAML. I found no documented tool for this. + +### Gaps +- I found no community-built n8n-to-Windmill converter, and no quantitative migration effort data. + +## 8. Known limitations and criticisms + +### Takeaway +The recurring criticisms are these: it is a developer-only tool with a steeper learning curve than n8n; it has a much smaller prebuilt integration catalog; its positioning is confusing (Retool vs. Airflow vs. Temporal); worker sizing and per-language pools need tuning; and the "open source" claim comes with caveats because of the proprietary CE binary and gated features. Reddit could not be accessed directly; Reddit search is blocked for this tool, so the sentiment here comes from blogs, HN mirrors, and vendor pages. + +### Cited Findings +- On HN, an early commenter could not tell whether Windmill competes with Retool, Airflow, or Temporal. The founder replied: "The critics is more than fair and our positioning is not very clear." — [HN mirror (brianlovin.com)](https://brianlovin.com/hn/38383138) (older, around 2023) +- On HN commentary about Windmill's benchmark claims, commenters said predictable per-job performance under concurrency matters more than raw speed. — [GeekNews summary (2023-11)](https://news.hada.io/topic?id=12005) (secondhand, older) +- An unverified community anecdote describes a problematic workflow affecting a broader instance. The source suggests checking worker isolation and resource limits. — [airframe.ai analysis](https://www.airframe.ai/product/windmill-dev/analysis) (low reliability) +- "Windmill's curve is steeper"; the integration catalog is "smaller and closer to developer-leaning targets"; teams need per-language worker pools. — [automationatlas.io](https://automationatlas.io/guides/n8n-vs-windmill-2026-comparison/) +- Self-hosting is a "slightly more complex due to multi-service architecture" setup. The question is framed as "do you want to click or do you want to type?", and for non-developers setting up webhooks, "n8n wins". — [Railway compare](https://railway.com/deploy/n8n-vs-windmill) (promotional) +- Postgres 18 is the default, and older data volumes (16 or earlier) block startup until you migrate. This is an upgrade friction point. — [Self-host docs](https://www.windmill.dev/docs/advanced/self_host) +- The legacy low-code app editor is now labeled "legacy" in favor of full-code React or Svelte apps. — [Docs intro](https://www.windmill.dev/docs/intro) + +### Inferences +- Upgrade churn is likely, given multiple releases per day and Postgres major-version changes. +- The CE caps (git sync for 2 users, 30-day retention, no audit logs, 3 workspaces) will push growing teams toward EE much as n8n's gating does, though Windmill's per-seat and per-CU pricing is public and comparatively cheap. + +### Gaps +- I could not access Reddit (r/selfhosted, r/n8n). No first-hand Reddit sentiment is included. +- I found no G2 or Capterra review data. diff --git a/docs/research/reports/kestra-windmill-activepieces-comparison.md b/docs/research/reports/kestra-windmill-activepieces-comparison.md new file mode 100644 index 0000000..238ec79 --- /dev/null +++ b/docs/research/reports/kestra-windmill-activepieces-comparison.md @@ -0,0 +1,101 @@ +> Ported from earlier research (2026-10-29) and sanitized for clean-room use: source-code-derived details removed. Not legal advice. + +# Three challengers still keep n8n's paywall + +None of the three tools gets you n8n's gated feature set for free. Kestra, Windmill and Activepieces are all open-core, and all three charge for most of the same governance features n8n charges for: audit logs, external secrets managers, log streaming and managed environment promotion are paid in every one of them. They do differ in which gates they open. **Windmill Community Edition is the most generous on people.** It gives you up to 50 users, 4 groups, folders, default roles, 3 workspaces and SSO for 10 users at no cost, which n8n Community cannot match. Its catch is that job retention is capped at 30 days and Git sync at 2 users. **Kestra's Apache-2.0 edition is the most generous on GitOps and scaling.** Git sync, purge-based retention and distributed clustering are free, but it allows only one shared Basic Auth login, so it suits a solo operator or a CI pipeline, not a team. **Activepieces' MIT Community Edition frees almost nothing on the list beyond retention and horizontal workers.** SSO starts on the $200/month Team plan, and Git, environments, audit and secrets sit in a custom-priced Ultimate tier. What it offers instead is the most permissive core license and the most n8n-like no-code experience. The licenses matter as much as the features. Kestra (Apache-2.0) and the Activepieces core (MIT) allow commercial hosting and embedding that n8n's Sustainable Use License forbids. Windmill's official images forbid offering the product as a managed service. No tool has an n8n importer, so every migration is a rewrite. The practical choice comes down to who builds your automations: business users (stay on n8n or try Activepieces), developers (Windmill), or data and platform engineers (Kestra). + +Per-tool detail lives in the research notes: [Kestra](../notes/kestra.md), [Windmill](../notes/windmill.md), [Activepieces](../notes/activepieces.md). The n8n baseline is covered in [n8n gated features reimplementation](n8n-gated-features-reimplementation.md), with supporting notes on [licensing](../notes/n8n-licensing-legal.md) and [feature feasibility](../notes/n8n-feature-feasibility.md). + +## The scorecard: where each tool's free tier beats or trails n8n Community + +The table compares self-hosted free editions as of late October 2026: Kestra 2.0.8, Windmill v1.853, Activepieces v0.92 and n8n 2.46. Sources are cited in the sections that follow. "Paid" means the feature requires a commercial plan. + +| Dimension | n8n Community (baseline) | Kestra OSS | Windmill CE | Activepieces CE | +|---|---|---|---|---| +| **SSO** | Paid (Business €667/mo+) | Paid (EE: OIDC, LDAP, SCIM; SAML unconfirmed) | **Free for 10 SSO users**; SAML, SCIM and custom OIDC paid | Paid (Team $200/mo; SCIM on Ultimate) | +| **Multi-user / RBAC** | Owner plus members; no sharing, admin, editor or viewer roles | **One shared Basic Auth account**; RBAC paid | **50 users, 4 groups, folders, default roles free**; custom roles and service accounts paid | Standard roles from Team; custom roles on Ultimate | +| **Shared projects / workspaces** | Paid (projects are a Business+ feature) | Namespaces free, but useless with one login; multi-tenancy paid | **3 workspaces free** (dev workspaces and forks count toward the 3) | Team collaboration is a paid-plan feature | +| **Log streaming** | Paid (Enterprise) | Paid (EE Log Shipper, CEF syslog) | Paid (OTel, Prometheus, S3 service logs) | Paid (Ultimate "event streaming") | +| **Execution data retention** | **Free, configurable** via env vars | **Free** via scheduled Purge flows | **Capped at 30 days or less**; unlimited is paid | **Free, configurable** (default 30 days) | +| **Multiple environments** | Paid (Business+) | DIY with namespaces and Git; Promote is paid | Deploy-to-prod UI paid | Paid (Ultimate releases) | +| **Git version control** | Paid (Business+) | **Free** (Git sync and push tasks, namespace sync) | Free for **up to 2 users** | Paid (Ultimate) | +| **External secrets** | Paid (Enterprise) | Paid (11 backends in EE) | Paid (Vault, Azure KV, AWS SM) | Paid (Ultimate) | +| **Audit logs** | Paid (Enterprise) | Paid | Paid | Paid | +| **HA / scaling** | Queue mode free; multi-main paid | **Distributed cluster free**; worker groups paid | Server and worker replicas free; autoscaling paid | **Stateless workers, Redis Sentinel free** | +| **License** | Sustainable Use License + proprietary enterprise code (not OSI) | **Apache-2.0** core + closed EE plugins | AGPLv3 source + proprietary code in official images | **MIT** core + proprietary enterprise-licensed portions | +| **Paid entry point** | Business €667/mo (annual) | Per-instance, sales-quoted | **From $120/mo; $20 per builder seat, ~$50 per compute unit** | Team $200/mo flat (25 users); Ultimate custom | +| **Product model** | Free-form node canvas | YAML-first declarative flows, form editor | Code-first scripts and flows in 10+ languages | Linear step builder, Zapier-like | +| **Integrations** | 1,600+ nodes | 2,400+ plugins (data and infrastructure heavy) | 50+ resource types + Hub + any npm/PyPI package | Large SaaS "pieces" catalog (check vendor's current count) | +| **Minimal ops stack** | Node.js + SQLite/Postgres (Redis for queue mode) | JVM + Postgres | Rust + Postgres only (no Redis) | Node.js + Postgres + Redis | +| **GitHub stars** | ~185k (older snapshot) | 30.1k | 18.3k | 25.3k | +| **n8n importer** | n/a | None | None ("a rewrite, not a conversion") | None | + +### n8n Community is less locked down than its gating suggests + +n8n's own documentation lists what self-hosted Community excludes: custom variables, environments, external secrets, external binary storage, log streaming, multi-main mode, projects, SSO (SAML, LDAP), workflow and credential sharing, and Git version control ([n8n CE features](https://docs.n8n.io/hosting/community-edition-features/)). Two items on your list are already free. **Execution pruning is configurable on self-hosted CE** through `EXECUTIONS_DATA_PRUNE` and `EXECUTIONS_DATA_MAX_AGE` ([n8n executions env vars](https://docs.n8n.io/hosting/configuration/environment-variables/executions/)). Queue mode with workers is also free. The cheapest self-hosted plan with SSO and Git is Business at **€667/month billed annually**, with 6 shared projects. Log streaming, external secrets and audit logging appear only under the sales-priced Enterprise plan ([n8n pricing](https://n8n.io/pricing/)). Measured against that baseline, each alternative trades some gates for others rather than removing them. + +## Open-core everywhere: the difference is which gate, and what the license lets you do + +### Kestra frees the pipeline but locks the door + +Kestra's core repository is **Apache-2.0**. Enterprise features ship as separate proprietary plugins, and the research found no license change in its history ([GitHub kestra-io/kestra](https://github.com/kestra-io/kestra)). In the open-source edition, Git version control runs as ordinary Kestra flows. The documented `SyncFlows`, `PushFlows`, `SyncNamespaceFiles` and bidirectional `NamespaceSync` tasks can be triggered by a schedule or a webhook ([Kestra Git docs](https://kestra.io/docs/version-control-cicd/git)). Retention also runs as flows: scheduled `PurgeExecutions`, `PurgeLogs` and `PurgeKV` tasks take date cutoffs and state filters ([Kestra purge guide](https://kestra.io/docs/administrator-guide/purge)). OSS can run as a distributed cluster with separate components ([Kestra OSS vs paid](https://kestra.io/docs/oss-vs-paid)). The weak point is identity. **The open-source edition has "one shared Basic Authentication account."** SSO through OIDC or LDAP, SCIM, RBAC, multi-tenancy, audit logs, log shippers, external secrets managers (11 backends, from Vault to Bitwarden) and worker groups are all Enterprise-only ([Kestra OSS vs paid](https://kestra.io/docs/oss-vs-paid); [Kestra secrets manager](https://kestra.io/docs/enterprise/governance/secrets-manager)). Kestra 2.0 made the paid tier more attractive. It added 159 per-action RBAC permissions with five role presets, and a Git-free **Promote** feature for moving flows between environments with diffs and drift status ([Kestra 2.0 release](https://kestra.io/blogs/release-2-0)). It also moved dashboards from OSS into EE, which shows that features can migrate behind the paywall between major versions. Enterprise is priced per instance with unlimited flows and executions, but no price is published ([Kestra pricing](https://kestra.io/pricing)). On user management, then, Kestra OSS is stricter than n8n Community, which at least gives each person their own login. On Git and scaling it is more generous. + +### Windmill frees the team but caps the history + +Windmill's license is the most complicated of the three. Per its LICENSE file, the backend and frontend source is AGPLv3, and the clients and OpenFlow spec are Apache-2.0, while enterprise-only code is proprietary. **The official "Community Edition" Docker images include "proprietary and non-public code."** Anyone may use them free, but may not "sell, resell, serve as a managed service, modify or wrap" them without an agreement ([Windmill repository, LICENSE file](https://github.com/windmill-labs/windmill)). The proprietary carve-out was added in September 2023. The binary terms were spelled out in March 2025, and white-labeling and embedding restrictions moved into the LICENSE file on 25 October 2026 ([LICENSE history](https://github.com/windmill-labs/windmill/commits/main/LICENSE)). The vendor calls Windmill "AGPLv3 (true OSS)" ([windmill.dev/compare/n8n](https://www.windmill.dev/compare/n8n)). That is accurate only for a binary you build yourself without the enterprise features. The images most self-hosters actually run behave like freeware on an AGPL core. Internal use, the n8n-replacement case, needs no commercial license. + +In return, Windmill CE gives you far more collaboration than any other free tier here. The published CE limits are **50 users, 4 groups, 3 workspaces, 10 SSO users, Git sync for up to 2 users, job retention of 30 days or less, 100 email triggers per day and 10 GiB of object storage**. SAML, SCIM, custom OIDC, service accounts, audit logs, external secret backends, the staging-to-prod deploy UI, Prometheus and OpenTelemetry, autoscaling, and Kafka, NATS and SQS triggers are all Enterprise ([Windmill pricing](https://www.windmill.dev/pricing)). Server and worker replicas run in CE because Postgres holds all state, and autoscaling is the gated part ([Windmill self-host docs](https://www.windmill.dev/docs/advanced/self_host)). The research team inferred that HA is ungated from these docs, but no explicit statement confirms it. Windmill is also the only one of the four vendors with transparent paid pricing. Enterprise starts at **$120/month**, priced at $20 per builder seat, $10 per non-builder, and about $50 per compute unit (2 worker-GB-month). There is a 40% discount for nonprofits, and a Pro variant for businesses under 10 employees and $250k revenue ([Windmill pricing](https://www.windmill.dev/pricing)). By the research team's estimate from that formula, five builders and four 2 GB workers come to roughly **$300/month at list price, under half of n8n Business**. The trade-off runs the other way on retention. **Windmill CE caps job history at 30 days, where n8n CE lets you keep executions as long as you like.** + +### Activepieces frees the license but almost nothing else + +Activepieces is MIT-licensed except for designated enterprise portions, which fall under an Enterprise license that requires a paid subscription for production use; per the LICENSE file, the split has been stable since February 2023 ([Activepieces repository, LICENSE file](https://github.com/activepieces/activepieces)). The vendor's "fully open source under the MIT license" claim ([Activepieces blog](https://www.activepieces.com/blog/activepieces-vs-n8n)) leaves out those portions. Per the pricing page, SSO, roles, audit logs, secret managers, SCIM, environments/releases and event streaming are all paid-plan features; Community Edition is aimed at individual or small-scale self-hosted use. Two things are genuinely free. **Retention is configurable via `AP_EXECUTION_DATA_RETENTION_DAYS`** (documented in the [Activepieces self-hosting docs](https://www.activepieces.com/docs)). Stateless workers scale horizontally, with jobs from crashed workers requeued and Redis Sentinel supported (same docs). + +The paid ladder starts with Plus at $20/month and Team at **$200/month flat for 25 users with SSO and standard roles**. Ultimate is custom-priced and adds SCIM, custom roles, "releases and Git Sync, audit logs and secrets", and event streaming. Embed starts at $36k/year ([Activepieces pricing](https://www.activepieces.com/pricing)). Plus and Team can be bought in-app on a self-hosted instance. There is a trap, though: per the Docker Compose install docs, **an instance started without `AP_EDITION=ee` "will not be able to activate a license key later"** ([Activepieces docs](https://www.activepieces.com/docs)), and the one-click marketplace installs all deploy Community. Against the n8n baseline, Activepieces makes Git and environments harder to reach, since they need a custom Ultimate quote where n8n puts them in Business. + +### The license is the real differentiator for anyone who hosts for others + +n8n's SUL limits use to "your own internal business purposes" and allows distribution only "free of charge for non-commercial purposes" ([n8n repository, LICENSE.md](https://github.com/n8n-io/n8n)). For an internal team replacing n8n, all four licenses are workable. For an agency, MSP or SaaS builder, the differences are large. **Kestra's Apache-2.0 edition is the only one whose complete free product can be hosted for clients without conditions.** The Activepieces MIT core is similarly free, but its embedding SDK and white-labeling are paid. Windmill's official images forbid managed-service use, which puts it in practice closer to n8n's restrictions than its "true OSS" marketing suggests. See [n8n licensing and legal notes](../notes/n8n-licensing-legal.md) for the full SUL analysis. + +## Three different products, and none of them is a drop-in n8n + +### Paradigm decides the audience + +These tools are not three versions of n8n. They are three different answers to the question of who builds the automation. **Kestra** describes itself as an event-driven platform for data, AI and infrastructure workflows declared in YAML. A form-based no-code editor, the YAML editor and an AI Copilot all edit the same flow ([GitHub kestra-io/kestra](https://github.com/kestra-io/kestra); [Kestra 2.0 release](https://kestra.io/blogs/release-2-0)). Third-party comparisons say business and app-centric automation is "usually easier in n8n" ([ZoomInfo comparison](https://pipeline.zoominfo.com/sales/kestra-vs-n8n)). **Windmill** turns scripts in "TypeScript, Python, Go, PHP, Bash, C#, SQL, Rust, Ruby and R, or any Docker image" into endpoints, flows, UIs and cron jobs ([Windmill docs](https://www.windmill.dev/docs/intro)). Its own comparison page concedes that n8n is "the fastest path when the automation is a chain of mainstream SaaS calls" ([windmill.dev/compare/n8n](https://www.windmill.dev/compare/n8n)). **Activepieces** is a linear, step-based builder that the vendor positions as easier than n8n's node-based canvas ([Activepieces blog](https://www.activepieces.com/blog/activepieces-vs-n8n)). It sits closer to Zapier than to n8n. Its flows are linear, with branches and loops, rather than arbitrary graphs, so complex n8n workflows with merges have no direct equivalent. + +### Integration counts are not comparable, and only one is close to n8n's catalog + +Kestra advertises **2,400+ plugins** ([Kestra plugins](https://kestra.io/plugins)), up from "more than 1,200" in a March 2026 press article ([The Next Web](https://thenextweb.com/news/orchestration-platform-kestra-raises-25m)). That number most likely counts individual tasks rather than services, and the catalog leans toward databases, warehouses, dbt and cloud infrastructure rather than CRM and marketing apps. Windmill offers only **"50+ pre-built resource types"** plus a community Hub, and relies on importing any npm or PyPI package. It counts n8n at "1,600+ pre-built nodes" ([windmill.dev/compare/n8n](https://www.windmill.dev/compare/n8n)). Activepieces markets a large, largely community-contributed catalog of SaaS integrations ("pieces"); check the vendor's site for the current count. It is the only alternative whose SaaS catalog approaches n8n's. Its pieces are distributed as TypeScript npm packages, which the vendor positions as easy to write. All three ship AI agent steps and MCP support. Kestra exposes flows as MCP tools in OSS, Windmill supports a long list of bring-your-own-key providers including Ollama ([Windmill AI docs](https://www.windmill.dev/docs/core_concepts/ai_generation)), and Activepieces advertises MCP support. AI is therefore not a reason to pick one over another. + +### Every migration is a manual rewrite + +No tool imports n8n workflow JSON. Windmill says so directly: **"Porting is a rewrite, not a conversion"** ([windmill.dev/compare/n8n](https://www.windmill.dev/compare/n8n)). Kestra publishes a migration guide for Pipedream but none for n8n ([Kestra Pipedream migration](https://kestra.io/resources/migration/pipedream)). Activepieces documents no n8n importer. The cost depends on what your n8n workflows contain. Code and HTTP Request nodes port almost one-to-one into Windmill scripts, Kestra script tasks or Activepieces code steps. Workflows built from many SaaS app nodes cost most to move to Windmill and Kestra, because each node becomes SDK code or an HTTP call. They cost least to move to Activepieces, which has matching pieces. Branch-and-merge graphs that rely on n8n's per-item execution model are hard to port to all three. The only documented migration is CFA Institute's SRE team, which moved fully off n8n to Windmill in early 2025 after a year of evaluation. They left to get "real programming capabilities and Git workflows" and needed "only brief training sessions" ([CFA Institute case study](https://www.windmill.dev/case-studies/cfa-institute)). That is a vendor-published case study with no effort figures. One consultant's anecdote put a Windmill rollout, including SSO, at 9 days against 3 for n8n, and the author flagged the small sample ([automationatlas.io](https://automationatlas.io/guides/n8n-vs-windmill-2026-comparison/)). Credentials never migrate cleanly from any of them, because n8n's documented workflow export leaves credential secrets encrypted with the instance's own key ([n8n CLI commands](https://docs.n8n.io/hosting/cli-commands/)), so every connection has to be re-created in the new tool. + +## Ops footprint and community health favor different winners + +### Windmill runs leanest, Activepieces sizes heaviest per flow + +**Windmill needs only PostgreSQL**, which holds both state and the job queue, with no Redis. Its Rust server and workers are stateless. The guideline is "1 worker per 1vCPU and 1-2 GB of RAM", and Compose also brings up an LSP container, native workers and Caddy ([Windmill self-host docs](https://www.windmill.dev/docs/advanced/self_host)). **Kestra 2.0** simplified its architecture considerably. A single Postgres instance can serve as both queue and repository, the Kafka Streams engine is gone, and workers connect outbound over gRPC with no database access ([Kestra 2.0 release](https://kestra.io/blogs/release-2-0)). The JVM means a heavier baseline than lightweight schedulers ([aitoolsatlas](https://aitoolsatlas.ai/tools/kestra/pros-cons)), and no official RAM minimum is published. **Activepieces** needs Postgres plus Redis. It offers a single-container PGLite "hobby" mode, but that mode "cannot scale, cannot move to Enterprise." Production guidance is **one worker (0.5 vCPU, 1 GB) per concurrent flow**, so 50 concurrent flows need 50 workers totalling 25 vCPU and 50 GB (production-setup and Docker pages of the [Activepieces docs](https://www.activepieces.com/docs)). For a small team, all three fit on a single modest VM, much like n8n with Postgres. The differences only matter at scale. + +### All three are active; only Kestra is well funded + +Kestra has **30.1k stars, weekly patch releases on two maintained lines, 2.0 as a one-year LTS, and a $25M Series A in March 2026** (about $36M raised in total) ([GitHub releases](https://github.com/kestra-io/kestra/releases); [The Next Web](https://thenextweb.com/news/orchestration-platform-kestra-raises-25m)). Activepieces has **25.3k stars and 357 contributors**, but is still on pre-1.0 versioning at v0.92 ([GitHub](https://github.com/activepieces/activepieces); [contributors API](https://api.github.com/repos/activepieces/activepieces/contributors)). Its funding figures conflict, ranging from a $0.5M convertible note to $6.4M depending on the source ([CB Insights](https://www.cbinsights.com/company/activepieces); [startups.fm](https://startups.fm/startups/activepieces)). Windmill has **18.3k stars, about 172 contributors and 30 releases in the 20 days before 29 October 2026** ([GitHub releases](https://github.com/windmill-labs/windmill/releases)). It comes from a YC S22 company that YC lists with 7 people and a sole founder ([YC](https://www.ycombinator.com/companies/windmill)). Its funding data is likewise sparse and conflicting. All three are an order of magnitude smaller than n8n, which an older snapshot put at roughly 184.8k stars ([openalternative.co](https://openalternative.co/compare/kestra/vs/n8n)). Expect fewer community templates, forum answers and tutorials than n8n users are used to. + +### Known criticisms cluster around churn, gating and audience fit + +Independent criticism of all three is thin. The research found no substantive Reddit threads and had to rely on review aggregators, which are of uneven quality. **Kestra's** recurring complaints are that the Enterprise price is unpublished and "requires a sales conversation for RBAC/audit features", the JVM footprint, and the YAML learning curve ([aitoolsatlas](https://aitoolsatlas.ai/tools/kestra/pros-cons)). Its 2.0 upgrade also breaks a lot: you must reach 1.3.x first, `ForEach` and `pluginDefaults` are removed, and the password rehash cannot be rolled back ([Kestra 2.0 migration guide](https://kestra.io/docs/migration-guide/v2.0.0)). **Windmill** is criticized as developer-only with a steeper learning curve, and for needing per-language worker pools ([automationatlas.io](https://automationatlas.io/guides/n8n-vs-windmill-2026-comparison/)). Its positioning is muddled, and the founder himself admitted that "our positioning is not very clear" ([HN via brianlovin.com](https://brianlovin.com/hn/38383138)). It also creates upgrade friction, for example by blocking startup on Postgres 16 data volumes now that the default is Postgres 18 ([Windmill self-host docs](https://www.windmill.dev/docs/advanced/self_host)). **Activepieces'** own docs carry the sharpest warnings. Code steps run unsandboxed by default in CE, and the default worker concurrency "widens the OOM blast radius" (workers page of the [Activepieces docs](https://www.activepieces.com/docs)). Reviewers add that Kubernetes and enterprise SSO documentation is sparse ([noviqip](https://noviqip.com/blogs/guides/activepieces-review-2026)), and that n8n is more flexible for code-heavy users ([G2](https://www.g2.com/compare/activepieces-vs-n8n)). One review claims Activepieces lacks flow versioning and subflows; treat that claim as unverified and check current product docs. + +## Match the tool to the person who builds the automations + +**Business users and no-code builders on a SaaS-heavy stack should stay on n8n Community.** Use the external tooling from the [n8n gated features analysis](n8n-gated-features-reimplementation.md) (CI-driven Git export, a forward-auth proxy, log shipping) rather than switching. No alternative gives this group a better free governance story. Activepieces is the only one with a comparable no-code experience and SaaS catalog, and its Community Edition is weaker than n8n's on collaboration. Activepieces becomes the right pick for one subgroup: **agencies, MSPs and SaaS builders who need to host or build on a permissively licensed core**, which n8n's SUL forbids. Even then, budget $200/month for SSO and an Ultimate quote for Git and audit. Start with `AP_EDITION=ee` from day one so you keep the upgrade path open. + +**Developer-led teams of up to about 50 people who want real multi-user access, RBAC and some SSO for free should choose Windmill.** It is the only option on this list where a team gets individual accounts, groups, folders and 10 SSO users at no cost. It also has the cheapest transparent paid path, from $120/month, if you need audit logs, unlimited retention or external secrets later. The price is a rewrite of every SaaS node into code, a 30-day retention ceiling on CE, and frequent upgrades. Avoid it if you plan to offer it to clients as a managed service. + +**Data, platform and infrastructure engineers who manage everything through Git and CI should choose Kestra OSS**, especially when one operator or a pipeline is the only "user". Free Git sync, free purge-based retention, free clustering and Apache-2.0 licensing make it the cleanest free option for GitOps-style orchestration. Its funding and LTS policy make it the lowest abandonment risk. Once more than one person needs their own login, Kestra means buying Enterprise at an unpublished per-instance price. + +**Teams that need SSO, audit logs, external secrets and log streaming together have no free option among these four.** The decision is about price. Windmill publishes rates starting at $120/month. n8n Business costs €667/month and reserves several of those features for Enterprise. Kestra Enterprise and Activepieces Ultimate are both sales-quoted. + +## Conclusion + +The question "which alternative escapes n8n's paywall?" has a dull answer: none of them does. Every open-core vendor here has reached the same conclusion as n8n about which features enterprises pay for, and audit logs, external secrets and log streaming are paid without exception. The useful question is which single gate hurts you most. If it is people (accounts, groups, SSO), Windmill removes it. If it is GitOps and scale, Kestra removes it. If it is the license itself, meaning the right to host or embed commercially, Kestra and the Activepieces core remove it. Retention is not a reason to switch at all: n8n already frees it, and Windmill makes it worse. + +That reframes the build-or-buy analysis from the [n8n gated features research](n8n-gated-features-reimplementation.md). The external-tooling approach to n8n remains competitive because the alternatives charge for nearly the same set of features. A switch only pays off when it fits your builders' paradigm, not when it saves on licensing. The trend also points against waiting for things to loosen. Kestra moved dashboards into EE in 2.0 and Windmill tightened its binary and white-label terms in 2025 and again in October 2026. Pick a tool whose free tier fits your needs today, and assume its gates will only get stricter. diff --git a/docs/research/reports/n8n-gated-features-reimplementation.md b/docs/research/reports/n8n-gated-features-reimplementation.md new file mode 100644 index 0000000..fe7e61d --- /dev/null +++ b/docs/research/reports/n8n-gated-features-reimplementation.md @@ -0,0 +1,64 @@ +> Ported from earlier research (2026-10-29) and sanitized for clean-room use: source-code-derived details removed. Not legal advice. + +# Rebuild n8n's paywall, but never inside it + +*Not legal advice. This report synthesizes license texts, case-law summaries, public documentation and pricing pages. Supporting detail is in [notes/n8n-licensing-legal.md](../notes/n8n-licensing-legal.md) and [notes/n8n-feature-feasibility.md](../notes/n8n-feature-feasibility.md). Before you rely on any of this commercially, have a lawyer review the plan, ideally one who knows both German and US software law.* + +A clean-room reimplementation of the features n8n gates behind its paid plans is legally and technically feasible. How safe it is depends on where the new code runs and who receives it, not on how good the code is. **Copyright protects n8n's code but not its features.** An independently written product that offers SSO, RBAC, Git environments, log streaming or external secrets, and is perhaps even compatible with n8n's workflow JSON, stands on firm ground in both the US and the EU. The danger begins once your code runs inside n8n. Files that n8n's license marks as Enterprise Edition are under a proprietary Enterprise License that assigns your modifications to n8n. The rest of the code is under the Sustainable Use License (SUL), which permits modification only for internal, non-commercial or personal use and permits distribution only free and for non-commercial purposes. Several features look gated but are already free on a self-hosted instance: execution retention and pruning, queue mode, concurrency limits and Prometheus metrics. Others can be approximated well with external tools: Git environments, workflow history, log shipping, insights and secrets injection. **The recommendation is to start with external tooling and sidecars, which carry the lowest risk. Move to a purpose-built alternative if you need real RBAC and SSO without paying. Pay n8n if you need n8n itself with those features in production. Do not fork n8n unless you are an internal-only user and willing to carry a large maintenance burden and real legal uncertainty.** For STaurtomation, the relevant path is the independent clean-room product (path 3 below). + +## Two licenses split the repository along a filename boundary + +n8n is not open source by its own account. It says that "open source licenses can't include limitations on use, so we do not call ourselves open source," and it calls its model "fair-code" ([n8n docs](https://docs.n8n.io/n8n-community-license/sustainable-use-license)). The project moved from Apache 2.0 plus Commons Clause to the SUL on 17 March 2022 and added an Enterprise License in August 2022 ([n8n docs](https://docs.n8n.io/n8n-community-license/sustainable-use-license); [LICENSE.md history](https://github.com/n8n-io/n8n/commits/master/LICENSE.md)). The SUL grants rights to "use, copy, distribute, make available, and prepare derivative works." It then limits them to three things: **use or modification "only for your own internal business purposes or for non-commercial or personal use,"** distribution "only if you do so free of charge for non-commercial purposes," and no altering or removing "any licensing, copyright, or other notices" ([LICENSE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE.md)). The termination clause says that use in violation "is not licensed." That wording makes the limits look like scope conditions rather than mere promises. Under the US *MDY v. Blizzard* condition-versus-covenant analysis, use outside those limits could therefore be copyright infringement and not just breach of contract ([InfoLawGroup](https://www.infolawgroup.com/insights/2010/12/articles/copyright/ninth-circuit-highlights-the-importance-of-welldrafted-software-licenses-and-terms-of-use)). + +One drafting detail matters a great deal. The SUL is visibly modelled on the Elastic License 2.0, which shares its notice and patent sentences word for word. ELv2 also says "You may not move, change, disable, or circumvent the license key functionality... and you may not remove or obscure any functionality... protected by the license key." **The SUL omits that sentence** ([Elastic-2.0 SPDX](https://spdx.org/licenses/Elastic-2.0.html); [LICENSE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE.md)). n8n's FAQ takes a stricter view than the plain text and lists "Use enterprise features that ask for a license key without an Enterprise license" and "Fork n8n's code to launch your own automation product" as not allowed ([n8n License FAQ](https://docs.n8n.io/n8n-community-license/community-license/license-faq)). An FAQ is not the license, and ambiguous standard terms are usually construed against the drafter. Still, this gap between the text and n8n's stated position is the least settled question in the whole analysis. The SUL also has no governing-law clause, so it is unclear whether German, EU or US law would decide a dispute. + +The Enterprise License is much stricter. Production use requires "a valid n8n Enterprise license." Copying and modification are allowed for development and testing. **n8n "retain[s] all right, title and interest" in any modifications or patches**, and copying, publishing, distributing and selling are otherwise forbidden ([LICENSE_EE.md](https://raw.githubusercontent.com/n8n-io/n8n/master/LICENSE_EE.md)). The SUL's scope preamble defines the boundary only by filename: files carrying an "ee" marker in their file name or directory name. Two practical consequences follow. First, anything derived from Enterprise-licensed code is effectively n8n's property. Second, the "development and testing" carve-out lets engineers read that code lawfully, but anyone who has done so has disqualified themselves from a clean-room team. For STaurtomation the rule is stricter still: no n8n source, of either license, is read by implementers. + +## Copyright doctrine favors reimplementation; contract and enforcement history set the limits + +The doctrine strongly supports rebuilding features. The CJEU's *SAS Institute v. World Programming* (C-406/10, 2012) held that "the functionality of a computer program... and the format of data files" are ideas that copyright does not protect, and that a lawful licensee may "observe, study or test" a program to determine those ideas ([Fieldfisher](https://www.fieldfisher.com/en/insights/sas-institute-inc-v-world-programming-limited)). EU Software Directive 2009/24/EC makes contract terms that override those study and interoperability rights void. The research team quoted those articles from memory, so check them against the text ([EUR-Lex](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32009L0024)). In the US, *Google v. Oracle* (2021) held that reimplementing about 11,500 lines of Java API declaring code was fair use, although commentators read the decision narrowly ([Jenner & Block](https://www.jenner.com/en/news-insights/publications/client-alert-us-supreme-court-holds-that-copying-declaring-code-is-fair-use)). The main US counterweight is *Bowers v. Baystate* (Fed. Cir. 2003), which enforced a contract ban on reverse engineering beyond what copyright requires ([Wikipedia](https://en.wikipedia.org/wiki/Bowers_v._Baystate_Technologies,_Inc.)). That matters less here than it might seem, because the SUL contains **no term prohibiting study or independent reimplementation**. Even a licensee who builds a competing product from scratch breaches nothing. + +Anti-circumvention law is a weaker threat than it first appears. Asked in its May 2025 DMCA notice whether it had "technological measures in place to control access," **n8n answered "No"** ([GitHub DMCA 2025-05-27](https://github.com/github/dmca/blob/master/2025/05/2025-05-27-n8n-io.md)). Platform policy is a separate matter. GitHub bans "software for bypassing checks for product licensing keys" regardless of statute ([GitHub DMCA policy](https://docs.github.com/en/site-policy/content-removal-policies/dmca-takedown-policy)). Trademark is simple: the SUL grants no trademark rights, n8n has a US application for "N8N" ([Justia](https://trademark.justia.com/970/27/n8n-97027061.html)), and its takedown explicitly complained that the fork had "used our name". Use your own name and limit references to nominative statements such as "compatible with n8n workflows." + +Enforcement so far has been selective and has relied on platforms. The only license-enforcement action on record is the May 2025 DMCA takedown against a fork that combined the three highest-risk factors: n8n's name, redistributed Enterprise-licensed code, and public npm packaging. n8n's complaint was that it "made all our paid Enterprise features freely available, which is obviously not allowed, as that code has a different license" ([GitHub DMCA](https://github.com/github/dmca/blob/master/2025/05/2025-05-27-n8n-io.md)). The framing is about Enterprise-licensed code, not about touching gates as such. Other "unlocker" forks that redistribute n8n's Enterprise code exist; they are outside the Enterprise License, and they are deliberately not named or linked here. A different pattern is the sreent/n8n fork ("tuflow"), created in September 2026, which claims to delete all enterprise code, rebuild the features, rebrand, and stay "for internal business use only." There is no recorded n8n response, and its clean-room claims have not been audited. **It is prior art only: its code is a derivative of n8n source and must not be read or copied by STaurtomation contributors.** No court has ever interpreted the SUL. One caution from a comparable case: in 2024 HashiCorp sent OpenTofu a cease-and-desist claiming that reimplemented functionality copied BSL code ([OpenTofu](https://opentofu.org/blog/our-response-to-hashicorps-cease-and-desist/)). Accusations happen even when the reimplementation is legitimate, so provenance records are what protect you. Unlike Elastic and Redis, n8n has **no permissively licensed past version to fork**. Its pre-2022 code was already under Commons Clause, so the OpenSearch and Valkey escape route does not exist. + +## Documented extension points of stock n8n + +This section is relevant only to the "external tooling" path (running unmodified n8n); it is not a design input for STaurtomation. The documented, ungated ways to extend or integrate a self-hosted n8n are: community nodes; backend external hooks loaded via `EXTERNAL_HOOK_FILES` (documented hooks include `n8n.ready` and `frontend.settings`); credential overwrites (`CREDENTIALS_OVERWRITE_DATA` / `CREDENTIALS_OVERWRITE_ENDPOINT`); the public REST API (`/api/v1/...` with an API key); CLI export and import; and direct database access ([external hooks docs](https://docs.n8n.io/hosting/configuration/external-hooks)). The docs describe **no built-in trusted-header or forward-auth login**. Seamless proxy SSO therefore needs an in-process hook that turns a verified identity header into an n8n session. One NixOS deployment does exactly this with oauth2-proxy and Kanidm ([thalheim dotfiles](https://git.thalheim.io/janet/dotfiles/src/branch/main/machines/eve/modules/n8n)), and [cweagans/n8n-oidc](https://gittrend.io/repo/cweagans/n8n-oidc) offers "bolt-on OIDC." Whether hook-based SSO complies with the license is officially unanswered. A user asked n8n in March 2026 and had no reply by April ([community thread](https://community.n8n.io/t/question-about-sso-via-custom-hooks-and-sul-compliance/283373)). + +## Per-feature difficulty: half the list is already free or easily done outside n8n + +Several items on the "limited" list are restrictions of the cloud plans, not of self-hosting. n8n Cloud caps execution retention at 7 days on Starter and 30 on Pro ([pricing](https://n8n.io/pricing/)), but on self-hosted Community **pruning is fully configurable** with `EXECUTIONS_DATA_PRUNE`, `EXECUTIONS_DATA_MAX_AGE` and `EXECUTIONS_DATA_PRUNE_MAX_COUNT` (0 means no limit), which the docs do not mark as license-gated ([executions env vars](https://docs.n8n.io/hosting/configuration/environment-variables/executions/)). Queue mode with workers is included in Community ([CE features](https://docs.n8n.io/hosting/community-edition-features/)). So are concurrency limits and the `/metrics` Prometheus endpoint ([monitoring](https://docs.n8n.io/hosting/logging-monitoring/monitoring/)). A free email registration unlocks folders, debug in editor and custom execution data. The truly gated Community features are SSO and LDAP, projects, sharing, variables, environments and Git, external secrets, external binary storage, log streaming and multi-main ([CE features](https://docs.n8n.io/hosting/community-edition-features/)). On the paid side, the cheapest self-hosted plan with SSO and Git is Business at **€667/month** billed annually, with 6 shared projects. "Unlimited" shared projects, custom roles, log streaming and external secrets appear only under Enterprise, which is sales-priced ([pricing](https://n8n.io/pricing/)). + +| Feature | Status in self-hosted CE | Best low-risk external approach | In-product clean-room difficulty | +|---|---|---|---| +| Execution retention / pruning | Free (env vars) | Configure; archive rows to cold storage before pruning | None needed | +| Queue mode, concurrency, metrics | Free | Configure; Kubernetes autoscaling on queue depth | None needed | +| Git version control, environments | Gated | Separate dev/prod instances; CI runs CLI export, commits, reviews, imports; community templates ([12721](https://n8n.io/workflows/12721-back-up-and-restore-n8n-workflows-with-github-sync/), [7304](https://n8n.io/workflows/7304-automated-workflow-backup-with-intelligent-change-detection-using-github/)) | Medium (credential remapping, merge) | +| Workflow history / diff | 24 h only | Git commit on every change gives unlimited history plus `git diff` | Low–medium | +| Insights dashboard | Summary only | Grafana or Metabase over Postgres or `/metrics` | Low–medium | +| Log streaming | Gated | Ship stdout/file logs via Vector or Fluent Bit; CDC on execution tables; global Error Workflow; hooks for lifecycle events | Medium (node and audit events are the hard part) | +| External secrets | Gated | Vault Agent / External Secrets Operator rendering into credential overwrites or env | Medium | +| Variables | Gated | `$env`, a config Data Table or a sub-workflow | Low | +| External binary storage | Gated | S3 mounted via FUSE/CSI into the filesystem path | Medium | +| SSO (SAML/OIDC/LDAP) | Gated | Forward-auth proxy (Authentik, Authelia, Pomerium) as an access gate; a hook for seamless login (grey zone) | Medium–high | +| Multi-user RBAC, sharing, unlimited projects | Gated (projects excluded from CE) | Separate instance per team; proxy-level method blocking (crude) | **High**: per-object authorization must be enforced on every API and UI surface | +| Multi-main HA | Gated | Active/passive main, fast restart, separate webhook processes | **High** (leader election, trigger dedup) | + +The pattern is clear. Externalizing works well for anything that consumes n8n's outputs, such as workflow JSON, execution rows, logs and metrics. It works badly for anything that must decide, request by request, who may see or edit an object. Authorization and active-active coordination can only be implemented inside the process, and inside the process is where the license constraints are tightest. + +## Four paths ranked from lowest to highest legal risk + +**1. External tooling and sidecars on stock Community Edition (lowest risk).** Proxies, CI pipelines, log shippers, secret agents and database dashboards run n8n unmodified, within its documented configuration and the internal-use grant. They involve no Enterprise-licensed code and no gate changes, and they survive upgrades better than patches do. This path covers retention, Git environments, history, insights, log shipping, secrets and access gating. It cannot deliver fine-grained RBAC, sharing or multi-main. Hook-based seamless SSO is a step up in risk. It is SUL-compatible on the text but officially unconfirmed, and hooks are an unstable in-process API. + +**2. Switching to an alternative tool (low legal risk, high migration cost).** Most open-core competitors gate the same enterprise set. Windmill Community caps SSO at 10 users and has no audit logs or external secret backends ([Windmill pricing](https://www.windmill.dev/pricing)). Activepieces puts SSO in its $200/month Team plan, and SCIM, audit and Git sync in Ultimate ([Activepieces pricing](https://www.activepieces.com/pricing)). Kestra's Apache-2.0 open-source edition includes Git versioning but sells SSO, RBAC, audit and secrets managers ([Kestra pricing](https://kestra.io/pricing)). Fully free stacks such as Airflow and Temporal are code-first, a different paradigm; their licensing was not re-verified in this research. In practice "free SSO and RBAC" means accepting either a different paradigm or another vendor's limits. See [kestra-windmill-activepieces-comparison.md](kestra-windmill-activepieces-comparison.md) for detail. + +**3. Independent, compatible product built clean-room (low copyright risk, very high effort).** A new codebase that imports n8n workflow JSON and offers its own SSO and RBAC is the only route to a *commercial* offering, and the doctrine supports it (*SAS*, *Google v. Oracle*). It is safe only with real discipline. Spec writers work from public docs and black-box behavior. A reviewer strips code expression out of the specs. Implementers have never read n8n source (of either license), nor source-derived descriptions of it. Everything is documented. Do not copy UI text, docs, icons or node descriptions, and do not use the n8n name. The practical obstacle is not the enterprise features but the hundreds of integration nodes that make n8n valuable, all under the SUL, which would have to be rewritten as well. + +**4. Fork with Enterprise-licensed code removed and features rewritten (moderate, uncertain risk; internal use only).** This is defensible on the SUL text: the SUL allows modification for internal use, contains no license-key clause, and the new code is your own. It is contrary to n8n's FAQ, untested in court, and immediately high-risk once you distribute it commercially or host it for others, because those acts fall outside the SUL's use and distribution conditions whatever the gating question. It requires keeping every copyright and licensing notice, adding the SUL's required modification notice, rebranding, pinning to a specific version (the CLA lets n8n tighten future license versions), and rebasing against a fast-moving upstream indefinitely. It is not an option for STaurtomation, which is a clean-room AGPL project. Below all four options sits the path not to take. **Running or distributing existing Enterprise-licensed code with gates disabled is outside the Enterprise License**, and it is precisely the conduct n8n has already taken down. + +## Conclusion + +The gated features are not hard because they are secret. The hard ones (RBAC, sharing, SSO, multi-main) are hard because they must make access and coordination decisions inside the process, which is exactly where n8n's license constraints are tightest. That changes the usual "build or buy" question. For most teams the useful split is outputs versus decisions. Everything that reads what n8n produces can be built freely outside it today, and much of the "limited" list turns out to be cloud-plan packaging that self-hosting already removes. Everything that decides access inside n8n must either be paid for, or rebuilt in a fork whose legality rests on one omitted sentence and an untested license with no governing-law clause. + +The recommended sequence for n8n users is as follows. Configure what is already free. Externalize Git environments, history, log shipping, insights and secrets. Gate access with an identity-aware proxy. If you need real per-object RBAC or SSO in production, either buy Business or Enterprise, or move to a tool whose free tier fits. A clean-room independent product is the only route to commercial use, and its real cost lies in the integration catalog rather than the enterprise features. The precedents also show that n8n's leverage is less about courts than about platforms such as GitHub and npm, and about its own name, so a project that stays off n8n's code, name and package namespaces avoids every enforcement action n8n has actually taken. diff --git a/docs/specs/001-staurtomation.md b/docs/specs/001-staurtomation.md new file mode 100644 index 0000000..e474cb8 --- /dev/null +++ b/docs/specs/001-staurtomation.md @@ -0,0 +1,345 @@ +--- +status: draft +--- + +# STaurtomation — Design + +- **Date:** 2026-10-29 +- **Status:** Draft for owner review (builder-check questions answered 2026-10-30) +- **Owner:** Lucas Winther (copyright holder) +- **Background research:** `docs/research/` (licensing analysis of n8n, feature/pricing comparisons of n8n, Kestra, Windmill, Activepieces). Sanitized for clean-room use. + +Marking convention: items the owner decided are stated plainly. Items marked **[call]** are the designer's call — sensible defaults the owner has not explicitly confirmed; the builder may revisit them with a stated reason. + +--- + +## 1. Intent + +n8n, Kestra, Windmill and Activepieces are all "open core": the free edition is usable, but the features that real organisations need — SSO, multi-user with roles, shared projects, git/environments, external secrets, log streaming, audit logs, HA — sit behind subscriptions or proprietary licenses. Several of them cannot legally be unlocked or forked into a product. + +STaurtomation is a **workflow automation platform that is completely open**, with **every feature available to everyone**, no subscriptions, no license keys, no proprietary code. It aims to replace all four products over time, starting with n8n. + +### Who it is for + +1. **Homelabbers.** One self-hosted box for glue: centralising notifications, integrating with OpenClaw, smart-home automation, and small scheduled jobs that would otherwise each need their own Docker image or cron entry. Must be light and work as a single-user install with team features invisible until needed. +2. **Universities**, with somewhat non-technical staff building automations. Visual editor first, clear errors, and institutional sign-in (SAML/OIDC: Entra ID, Authentik, Shibboleth-style IdPs), many users, shared projects, roles. +3. **Companies**, primarily for small-scale prototyping. Ease of use and low-maintenance operation (STaurtomation keeps nodes and the platform itself updated, under admin-controlled rules) matter most. Scheduled AI queries are a core use case. + +### What success looks like **[call]** + +- A non-technical university staff member builds, tests (with test data and visible node input/output) and schedules a working workflow without help. +- The same install stays up to date for months under admin-set update rules without breaking existing workflows. +- An n8n user imports their workflows, sees clearly what converted and what didn't, and runs them. +- A homelabber goes from `docker compose up` to a running scheduled workflow in minutes. + +--- + +## 2. Goals, non-goals, anti-goals + +### Goals + +- **Feature superset** of n8n, Kestra, Windmill and Activepieces, **including all of their premium/enterprise features**, delivered in phases (§9). Release 1 targets n8n. +- **Importers** for each product's workflow format. +- **Compatibility layers** to run third-party nodes: n8n community nodes first; later Kestra plugins and Activepieces pieces. +- **Polyglot code execution** via a runner architecture (TypeScript/Bun and Python first; R, Rust, Java, C# later). +- **AI on equal footing across providers**, plus an in-editor AI workflow assistant. +- **Admin-controlled updates** with semver rules and prominent security notices. + +### Non-goals (for now) + +- A hosted SaaS offering run by the project. +- Matching every one of n8n's ~400+ built-in integrations at launch (§6.4 defines the release-1 node set; the rest arrive via community-node compatibility and later node packages). +- Heavy data-engineering orchestration (Kestra/Airflow-style backfills at scale) in release 1 — later phase. + +### Anti-goals (failure even if it "works") + +- **Any proprietary or license-incompatible code in the codebase.** A single contaminated file undermines the whole project. +- **Any feature gated by edition, license key, user count or payment.** +- **Becoming developer-only** (Windmill/Kestra-style learning curve). Code is available; it is never required for common tasks. +- **Forced updates.** Nothing updates without an admin-configured rule allowing it. +- **Silent data loss on import.** Unsupported things are kept and flagged, never dropped. + +--- + +## 3. Constraints + +### 3.1 Licensing and ownership + +- **License:** AGPL-3.0-or-later for the whole project. **[call: AGPL over plain GPL]** — owner chose "GPL/AGPL"; AGPL is chosen because STaurtomation is network software and AGPL closes the hosted-modification gap. +- **Ownership:** the owner retains copyright and the freedom to relicense or dual-license. Therefore **all outside contributions require a Contributor License Agreement (CLA)** granting the owner the necessary rights. **[call: CLA rather than DCO-only, since DCO does not preserve relicensing rights]** +- Every source file carries an SPDX header: `SPDX-License-Identifier: AGPL-3.0-or-later`. +- **Dependencies:** only licenses compatible with AGPL-3.0 (MIT, BSD, ISC, Apache-2.0, MPL-2.0, LGPL, GPL-3.0, AGPL-3.0, etc.). CI enforces this with an automated license allowlist check; unknown or incompatible licenses fail the build. +- **Trademarks:** never use "n8n", "Kestra", "Windmill" or "Activepieces" as or in product, package or node names. Nominative use only ("imports n8n workflows", "compatible with n8n community nodes"), with a non-affiliation note in docs. + +### 3.2 Clean-room rules (non-negotiable) + +These go into the repository's agent instructions (`CLAUDE.md`/`AGENTS.md`) and `CONTRIBUTING.md`. + +1. **No code copied** from n8n, Kestra, Windmill, Activepieces or any other repository unless its license is permissive and AGPL-compatible **and** the copy is recorded in `THIRD_PARTY.md` with source, license and commit. In practice: do not copy from those four at all, including their permissively licensed parts, unless the owner explicitly approves. +2. **Do not read the source code** of n8n, Kestra, Windmill or Activepieces (including their `.ee`/enterprise code, internal packages, and the `n8n-workflow` / `n8n-nodes-base` packages) while working on STaurtomation. This applies to humans and AI agents, including via web search results and npm package contents. +3. **Allowed inputs:** public documentation and user guides, published file formats observed from exported files, public REST API docs, published specifications (e.g. Windmill's OpenFlow spec, which is Apache-2.0), observed behaviour of a running instance, screenshots, and third-party MIT/Apache-licensed community nodes/plugins (as *test subjects* for compatibility — reading them to learn which interface they consume is allowed; copying their code into STaurtomation is not, except under rule 1). +4. **Interface reimplementation** (for compatibility layers, §7) is done from documentation and from observing what community packages call, never from the original library source. Each compatibility layer keeps a `PROVENANCE.md` noting the documentation pages and test packages used. +5. If anyone realises they have been exposed to prohibited source for a given area, they record it and do not implement that area. +5a. **AI agents** (the expected primary builders) are allowed to implement every area, including the high-risk ones, despite the likelihood that their training data contains public source of those products. Because the project must supersede these tools, never copy them, the following **guards are mandatory**: + - **Similarity scanning in CI:** an automated code-similarity check (token/winnowing fingerprinting, e.g. JPlag or an equivalent tool, used as a CI tool only, not a dependency) compares every change against fingerprints of n8n, Kestra, Windmill and Activepieces. The reference corpus is fetched and fingerprinted inside an isolated CI job; reports show only *our* file, line range and score — never the matched third-party code — so builders are not exposed. Above-threshold matches block merge until a human reviews and rewrites. + - **Per-PR provenance note** (PR template): which public docs, specs, exported files or observed behaviour the change was based on; affirmation that no prohibited source was consulted. Mandatory for compatibility, importer and expression work. + - **Dependency denylist:** CI fails if the lockfile contains `n8n-workflow`, `n8n-core`, `n8n-nodes-base`, `@n8n/*`, `@n8n_io/*`, `@activepieces/*` (except as listed test fixtures outside the shipped product, if ever approved), or Kestra/Windmill packages. + - **Agent tooling rules:** agents must not clone, fetch, `npm view`/unpack or web-browse into those products' source repositories or packages; only their documentation sites and exported artifacts. + - **Human sign-off** on PRs touching the importer, expression compatibility, or any compatibility layer. + - **No naming mimicry:** internal names, file layout and identifiers follow STaurtomation's own conventions, not the original products'. Where n8n-facing names are unavoidable (importer mapping tables keyed by n8n node type strings, compat-layer public interface), they are confined to the importer/compat packages. +6. **Legal review gate:** the n8n community-node compatibility layer (§7.1) reimplements a third party's programming interface. That is generally defensible (interfaces/functionality are not protected expression in the EU — *SAS v WPL*; *Google v Oracle* by analogy in the US) but is the project's highest legal-risk area. It ships only after the owner obtains legal review. Not legal advice. + +### 3.3 Platform conventions (from `bun init`'s CLAUDE.md, adopted verbatim in the repo) + +- Bun, not Node.js: `bun `, `bun test`, `bun build`, `bun install`, `bun run`, `bunx`. Bun loads `.env` automatically (no dotenv). +- `Bun.serve()` with routes and WebSockets — no Express. +- `bun:sqlite` for SQLite, `Bun.sql` for Postgres, `Bun.redis` for Redis, built-in `WebSocket`, `Bun.file`, `` Bun.$ ``. +- Frontend via HTML imports served by `Bun.serve()` — no Vite. + +--- + +## 4. Architecture (decided parts) + +### 4.1 Stack + +| Area | Choice | +|---|---| +| Language/runtime | TypeScript on Bun | +| HTTP/API/WebSockets | `Bun.serve()` routes, with a thin in-house layer for auth, input validation and permission checks **[call: no web framework]** | +| Frontend | React + TypeScript SPA via Bun HTML imports; React Flow (xyflow) for the canvas; shadcn/ui + Tailwind (via `bun-plugin-tailwind`); TanStack Query and TanStack Router | +| Databases | SQLite (`bun:sqlite`) for single-box installs; PostgreSQL (`Bun.sql`) for multi-user/HA. Same schema, both supported and tested in CI. | +| Queue/coordination | Redis (`Bun.redis`) optional, needed for HA/multi-main **[call: Postgres-only queue is acceptable if the builder prefers; must work with zero extra services in single-box mode]** | +| Tests | `bun test` | +| Packaging | One Docker image containing server + editor + a default Bun runner; Docker Compose and Helm examples | + +### 4.2 Deployment shapes + +- **Single box (homelab):** one container, SQLite, embedded runner. Team features exist but stay out of the way (single owner account, no project UI clutter until a second user or project is created) **[call]**. +- **Team (university/company):** Postgres, one or more main instances, separate runners. +- **HA:** multiple main instances behind a load balancer (leader election for scheduler/trigger ownership), many runners. All of this is free — it is one of n8n's paid features. + +### 4.3 Runners + +Modelled on GitHub/Gitea Actions runners and on the concept (not the code) of n8n's task runners. + +- A runner is a separate process, possibly on another machine. It **registers** with the server using a registration token, connects outward over **WebSocket**, receives jobs, executes them, streams logs and results back. +- **Runner types per language:** Bun/TypeScript and Python in release 1; R, Rust, Java, C# later. A Node.js runner exists as fallback for community nodes that don't work on Bun **[call]**. +- **Labels** route jobs (`python`, `gpu`, `lan`, …). Scaling = add runners. +- **Isolation modes:** execute in-process (fast, trusted code) or in a throwaway container (untrusted community nodes, user code, the "job that would need its own Docker image" homelab case). Admin chooses defaults per project **[call]**. +- **Runner protocol is documented and versioned** (`docs/runner-protocol.md`) so third parties can write runners for new languages without core changes. +- Runners never receive more secrets than the job needs. + +### 4.3a Threat model **[call]** + +- On multi-user installs, workflow editors are **not** trusted with the server or with other projects' data. Instance admins are trusted. +- Expressions always run in a sandbox with no file/network/process access, on every install type. +- **Team installs default to container isolation** for user code steps and community nodes; in-process execution is an explicit per-project admin opt-in. Single-box installs default to in-process (one trusted owner) and offer container mode when a container runtime is available (Docker socket or rootless Podman mounted into the container — documented as optional in Compose). +- Credentials are decrypted only for the job that uses them and are never returned to the editor UI after saving. + +### 4.4 Workflow engine + +- A workflow is a directed graph of nodes. Data flows between nodes as **lists of items** (each item a JSON object plus optional binary attachments). **[call]** This model is chosen because it makes n8n import and community-node compatibility feasible; it is a well-known general concept. +- Executions are persisted with per-node input/output (subject to retention and redaction settings). +- Triggers: manual, schedule, webhook, called-by-another-workflow, form, chat, plus trigger nodes from packages. +- **Expressions:** an expression language for referencing previous nodes' data inside parameters, evaluated in a sandbox. A separate **n8n-expression compatibility mode** (built from n8n's public docs) is used for imported workflows so they keep working **[call]**. +- Binary data stored on filesystem or S3-compatible storage (free; paid in n8n). +- Concurrency limits per workflow/project/instance; retries with backoff; error workflows. + +### 4.5 Data model highlights **[builder decides details]** + +Users, identities (linked IdP accounts), roles, projects, project memberships, folders, workflows (+ versions), credentials (encrypted at rest), variables, executions (+ per-node data), tags, environments, audit events, update/package state. + +--- + +## 5. Identity, access and governance + +### 5.1 Authentication + +- **Library:** Better Auth (MIT) for username/password, sessions, TOTP 2FA, OAuth social login and OIDC/SAML via its SSO plugin; `@node-saml/node-saml` (MIT) as fallback for SAML edge cases; `ldapts` (MIT) for LDAP/AD. **[call]** The owner suggested Passport; the call is Better Auth because it is framework-agnostic (fits `Bun.serve()`'s standard `Request`/`Response`) and covers sessions/2FA/orgs. **First builder task: verify Better Auth's SAML and SCIM maturity and Bun compatibility. If it falls short, use Passport (MIT) with the relevant strategies behind an adapter.** +- **Must-have:** SAML 2.0 and OAuth2/OIDC. **Entra ID and Authentik are first-class:** step-by-step setup docs and automated integration tests (Authentik in a test container; Entra ID against a test tenant, possibly a manual/nightly job). +- Also: LDAP/AD, SCIM 2.0 provisioning, local accounts, 2FA with admin enforcement, social login (Google/GitHub/Microsoft). **[call on scope; owner delegated]** +- API keys with scopes for the public API. + +### 5.2 Identity mapping + +- Map IdP groups/claims/attributes → instance roles, project memberships and project roles, with a rules UI (e.g. "Entra group `automation-admins` → instance admin"). +- **Admins can make custom edits per user.** Manual edits are flagged as overrides and survive subsequent logins/syncs; an explicit "reset to IdP mapping" action reverts them **[call on override semantics]**. + +### 5.3 Authorization + +- Instance roles: owner, admin, member **[call]**. +- Projects: unlimited, with project roles admin / editor / viewer, plus **custom roles** built from fine-grained permissions. +- Sharing workflows and credentials across projects/users; personal projects per user. +- Folders within projects. +- Permission checks are enforced server-side on every API route and in the public API; the UI only reflects them. + +### 5.4 Governance features (all free) + +- **Audit log** of security-relevant and admin events, searchable, exportable, retention-configurable. +- **Log streaming** of audit and execution events to destinations: syslog, webhook, Sentry, OpenTelemetry/OTLP, plus file/stdout **[call on destination list]**. +- **Execution data retention**: global and per-project max age / max count, pruning, and what to save (success/failure/manual/progress). +- **Data redaction**: per workflow/project option to not store input/output of executions, or to mask fields. +- **Metrics**: Prometheus endpoint + OTLP metrics; health endpoints. +- **Insights**: dashboards of executions, failures, durations, time saved, over any date range. +- **Worker/runner view**: live status of runners, jobs, load. +- **2FA enforcement**, session policies. + +--- + +## 6. Building and running workflows + +### 6.1 Editor + +- Canvas (React Flow) with node panel, parameter forms, expression editor with autocomplete, keyboard shortcuts, copy/paste of nodes as JSON. +- **Test data and inspection (must-have):** + - Run a single node, a node and everything upstream, or the whole workflow from the editor. + - **See each node's input and output** after a run, as table / JSON / schema views, including binary previews. + - **Pin test data** on any node (paste JSON, edit, or pin from a previous execution's output) so downstream nodes can be built without re-triggering upstream ones. Pinned data is used only for manual/test runs, never production runs. + - **Debug from a past execution:** load a past (e.g. failed) execution's data into the editor and re-run. +- **Workflow history:** every save versioned, unlimited by default (retention configurable), named versions, visual diff between versions, restore. +- Execution list with search/filter including custom execution data. +- Templates/examples gallery **[call: local, shipped with the app; no external template service required]**. + +### 6.2 Sub-workflows (must-have) + +- A workflow can call another workflow (sync, waiting for the result; or async, fire-and-forget), passing input items and receiving output items. +- Callable workflows declare an input schema (fields and types) so callers get a form, and an output. +- Permission controls on who may call a workflow (same project, specific projects, any). +- Recursion/loop protection and depth limits. + +### 6.3 Credentials, variables, secrets + +- Credentials encrypted at rest with an instance key; credential types defined by node packages; OAuth2 credential flow handled by the platform. +- **Variables** (instance/project/environment scoped) referenced in expressions. +- **External secrets** providers: HashiCorp Vault/OpenBao, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, Infisical, Bitwarden Secrets Manager, plus environment/file-based injection **[call on list]**. + +### 6.4 Release-1 built-in nodes + +- **Triggers:** manual, schedule (cron + simple "every X" picker), webhook, called-by-another-workflow, form, chat. +- **Core/flow:** HTTP request, if, switch, merge, loop/split-in-batches, set/edit fields, code transform helpers (filter, sort, limit, aggregate, split out, remove duplicates), wait, execute sub-workflow, stop-and-error, error trigger, respond-to-webhook, no-op. **[call on exact list]** +- **Code:** TypeScript/JavaScript (Bun runner) and Python (Python runner). +- **AI:** chat/completion node, agent node with tools (other nodes and sub-workflows usable as tools), embeddings, structured output, agent memory (buffer + database-backed), document loaders/text splitters, vector store nodes (pgvector, Qdrant, in-memory) with a retriever, and simple evaluations (run a workflow over a test dataset and score outputs) **[call: the AI items beyond chat/agent are phase 3]**. See §8. +- **Human-in-the-loop:** pauses the execution until a person approves / rejects / fills a form. Delivery via email, link, in-app notification and (through other nodes) chat; assignable to a user or role; optional deadline with a timeout branch; resumes durably across restarts. +- **Data:** built-in data tables (simple tables stored in STaurtomation, usable from workflows) **[call]**. +- Everything else comes via node packages and the compatibility layer. + +### 6.5 Node packages and SDK + +- Nodes are distributed as packages (npm-compatible) with a STaurtomation node SDK (TypeScript), versioned with semver. +- Node versions installed side by side; each workflow pins the node versions it was built with until explicitly upgraded. +- Admin controls: allowlist/denylist of packages, private registry support. + +### 6.6 Environments and source control (git) + +- Connect an instance (or project) to a git repository (Gitea, GitHub, GitLab, any git over SSH/HTTPS). +- Workflows, credentials **(metadata only, never secrets)**, variables, folders, tags, data-table schemas serialized to a stable, diff-friendly text format. +- Push/pull from the UI and API; branch-per-environment model (e.g. `dev` → `staging` → `prod`), with an instance bound to a branch and optional read-only protection on production instances. +- Diff and conflict display before pulling/pushing; promotion between environments via git merge or an in-app "promote" action. + +### 6.7 Public API, CLI, MCP + +- Versioned REST API covering everything the UI can do (OpenAPI spec published). +- CLI for import/export, user management, backups. +- MCP server exposing selected workflows as tools for external AI agents **[call]**. + +--- + +## 7. Importers and compatibility layers + +### 7.1 n8n (release 1) + +- **Fidelity (owner decision): best effort, with clear warnings.** STaurtomation's engine follows its own semantics; it does not have to reproduce n8n's execution order, item linking, merge/branch waiting or error behaviour exactly. The importer warns per workflow and per node where behaviour may differ (known-difference list maintained in docs), and imported workflows start inactive so the user tests them first. No reference n8n instance is required in CI. +- **Importer:** accepts n8n workflow JSON (file, paste, or bulk directory/ZIP). Behaviour learned from exported files and public docs only. + - Nodes with a STaurtomation equivalent are converted; their parameters mapped; n8n expressions kept and evaluated in n8n-expression compatibility mode. + - Nodes that are n8n community nodes are mapped to the installed community package via the compatibility layer. + - Anything else becomes a **placeholder node** that preserves the original type and parameters, is visibly marked, and blocks activation until resolved. + - A per-import **report**: converted / via compatibility / placeholders, plus credential types needing setup (credentials are not exported by n8n with secrets; user re-enters them). + - Optional import of n8n credentials export files and the n8n public API (pull directly from a running n8n instance) **[call]**. +- **Community-node compatibility layer:** loads n8n community node npm packages (third-party, usually MIT) and runs them in a Bun runner (Node.js runner fallback), providing a clean-room reimplementation of the node-facing interface those packages consume — built from n8n's public node-development docs and from observing what MIT-licensed community packages call. The substitute module that packages import must be our own code. See §3.2 rules 3–6, including the legal-review gate. +- **Built-in n8n node coverage:** n8n's built-in nodes are under n8n's restrictive license and cannot be reused. STaurtomation writes its own equivalents from public docs; the importer maps n8n node type names to them. Coverage grows over time, prioritised by how commonly nodes appear in imported workflows **[call]**. + +### 7.2 Later phases + +| Product | Importer | Compatibility | +|---|---|---| +| Kestra | YAML flows → STaurtomation workflows (tasks → nodes, triggers, inputs, namespaces → projects/folders) | Java runner able to execute Kestra plugins (Apache-2.0) through a clean-room reimplementation of the plugin interface from Kestra's public docs | +| Windmill | OpenFlow JSON/YAML (published Apache-2.0 spec) and scripts → workflows and code nodes | Scripts run natively on the matching language runner | +| Activepieces | Exported flow JSON → workflows | Activepieces pieces (MIT, TypeScript) via a pieces adapter **[call: desirable, not committed]** | + +### 7.3 Feature superset from the other three (later phases) + +- **From Kestra:** flows-as-code (YAML representation of every workflow, editable side-by-side with the canvas), namespaces, event triggers (Kafka, AMQP, MQTT, etc.), backfills, scheduled purge, worker groups. +- **From Windmill:** scripts as first-class reusable units in many languages, per-script dependency locking, app/UI builder for internal tools, workspaces, Postgres CDC/WebSocket/SQS/NATS triggers, multiplayer editing. +- **From Activepieces:** simple step-based builder mode for beginners, approvals, tables, embedding/white-label SDK for SaaS builders, MCP-first agents. +- And each product's premium features listed in `docs/research/`. + +--- + +## 8. AI + +- **Providers on equal footing:** OpenAI, Anthropic, Google, Mistral, OpenRouter, Ollama, any OpenAI-compatible endpoint (LM Studio, vLLM, …), and OpenClaw. One provider interface; each provider a small plugin; keys stored as ordinary credentials (so external secrets work). +- **Workflow assistant** (Supabase-assistant-like) in the editor: describe what you want → it builds/edits the workflow, explains nodes, diagnoses failed executions. + - Configured with a **system-wide** API key (admin) and/or a **personal** key on a user's account. **[call]** Personal key takes precedence; admins can disable the system key for some roles; usage visible per user. + - Every change is proposed as a **diff on the canvas** that the user accepts or rejects; it never activates or runs a workflow without confirmation **[call]**. + - Works with any configured provider, including fully local models. + +--- + +## 9. Updates and maintenance + +- **Never forced.** Updates apply only under admin-configured rules. +- **Semver update rules**, separately for the core and per node package: off (notify only) / patch only / minor+patch / pinned. Defaults: core = notify only; node packages = patch only **[call]**. Optional "auto-apply security fixes only". +- **Clear notices:** banner + updates page with changelogs; **security fixes are highlighted** with severity and advisory/CVE ID; notifications via email, webhook, and an internal "update available" trigger usable in workflows. +- **Safety:** pre-migration database backup; node versions side-by-side so running workflows aren't changed underneath; one-click rollback of node packages; documented core downgrade path **[call]**. +- **Supported install methods in release 1 [call]:** Docker/Compose and Helm only. Core updates are therefore notices plus automatic database migrations on start; no in-app core self-updater in release 1. Node-package updates are applied live by the server and coordinated across HA main instances (one instance installs, all switch over together) and runners (fetch on demand). +- **Container installs:** the app does not replace its own image; it shows the new tag and the exact command, and is compatible with tools like Watchtower. +- **Advisories:** the project publishes a signed release/advisory feed the app polls (can be disabled for air-gapped installs) **[call]**. + +--- + +## 10. Phasing + +| Phase | Content | +|---|---| +| 0. Foundation | Repo, LICENSE (AGPL-3.0-or-later), CLA, `CLAUDE.md`/`AGENTS.md` with clean-room and Bun rules, `CONTRIBUTING.md`, `THIRD_PARTY.md`, CI (tests, typecheck, lint, dependency-license allowlist, SPDX header check) | +| 1. Core | Engine, item model, expressions, runners protocol + Bun & Python runners, SQLite/Postgres, editor with test data/IO inspection/pinning, sub-workflows, release-1 nodes, credentials, local auth | +| 2. Teams | SSO (SAML/OIDC with Entra ID & Authentik tests, LDAP, SCIM), identity mapping, RBAC + custom roles, projects, sharing, folders, variables, audit log | +| 3. n8n parity | Git environments, external secrets, log streaming, retention/redaction, workflow history + diff, insights, metrics, runner view, HA multi-main, S3 binary storage, public API + scopes, update system, AI nodes + assistant, human-in-the-loop | +| 4. n8n migration | n8n importer, n8n-expression compatibility, growing built-in node coverage | +| 4b. Community-node compatibility | n8n community-node layer — **only after legal review** | +| 5+ | Kestra importer/compat + Java runner; Windmill importer + R/Rust/C# runners; Activepieces importer/pieces; feature superset items in §7.3 | + +### Releases + +- **Release 1 — homelab-ready (owner decision: homelab first, no compatibility layer).** Phase 0 + Phase 1, plus from later phases **[call on this selection]**: AI chat/agent nodes, human-in-the-loop, update notices (security highlighting; node-package semver rules), retention settings, Prometheus metrics, and the **best-effort n8n importer** (§7.1, built-in node mapping + placeholders, no community nodes). Single-box Docker Compose install is the reference deployment. Local accounts plus OIDC login are enough. **[call: OIDC in R1 because homelabbers commonly run Authentik]** +- **Release 2 — teams/n8n parity:** rest of Phases 2–4 (SAML incl. Entra ID, LDAP, SCIM, RBAC, projects, git environments, external secrets, log streaming, audit, HA, AI assistant, etc.). +- **Release 3 — community-node compatibility** (Phase 4b), gated on legal review; ships when cleared, independent of other work. +- Release 1 must still be production-quality in what it includes (stable schema migrations from day one, upgrade path to later releases, security hardening). + +The builder may reorder within phases if dependencies demand it. + +--- + +## 10a. Who builds it (owner decision) + +Primarily a **team of AI agents**, with human contributors (under the CLA) and possibly a part-time maintainer provided by the owner's university. **Optimise for AI-first development:** small, independently verifiable tasks; strong automated checks (types, tests, license/similarity guards) so agents get fast feedback; thorough agent docs (`CLAUDE.md`/`AGENTS.md`, per-package READMEs, ADRs for decisions); no tribal knowledge. No fixed deadline. + +Owner-supplied resources, needed by Release 2: an Entra ID test tenant + CI credentials; legal review of the compatibility approach (blocks Release 3 only). + +## 11. Left to the builder + +- Detailed database schema, migration tooling, internal module layout (monorepo layout recommended). +- Queue implementation (Postgres-based vs Redis), scheduler/leader-election design. +- Expression language syntax for native STaurtomation workflows and the sandboxing approach. +- Workflow serialization format for git (must be stable and diff-friendly). +- Exact runner protocol messages, container isolation backend (Docker/Podman/rootless). +- UI design system details, beyond the stack in §4.1. +- Testing strategy beyond: `bun test` unit/integration tests, both databases in CI, IdP integration tests for Entra ID and Authentik, importer golden-file tests built from self-made n8n exports. +- Which further integrations to build first after the release-1 node set. + +## 12. Open verification items for the builder + +1. Better Auth: SAML maturity, SCIM plugin maturity, Bun compatibility (fallback: Passport behind an adapter). +2. Bun compatibility of the most popular n8n community nodes (decides how much the Node.js fallback runner matters). +3. React Flow and the remaining frontend stack under Bun's bundler (HTML imports) with Tailwind via `bun-plugin-tailwind`. +4. Legal review of the compatibility-layer approach (§3.2 rule 6) before §7.1's compatibility layer ships. diff --git a/docs/specs/README.md b/docs/specs/README.md new file mode 100644 index 0000000..0a7a7d8 --- /dev/null +++ b/docs/specs/README.md @@ -0,0 +1,10 @@ +# Specs + +Approved specifications from the superpowers brainstorming workflow. Nothing non-trivial gets +implemented without one. + +- Naming: `NNN-short-slug.md`, zero-padded, sequential. +- A spec states **what** and **why**, plus acceptance criteria. Not **how**. +- Front matter: `status: draft | approved | implemented | superseded`. No link to a plan — plans are + removed before merge. +- Never delete an implemented spec; it is the record of intent.