Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Revoluzen

Revoluzen Flow

Local-first data pipeline engine

Visual ETL on a vectorised DuckDB core — on your laptop, your VM, your rules.

CI Security Scan License Python Version

Quick start · What it looks like · Why · Connectors · Docs


git clone https://github.com/revoluzen-io/revoluzen-flow.git
cd revoluzen-flow
cd frontend && npm ci && npm run build && cd ..
python -m venv .venv && source .venv/bin/activate
pip install -e .
python -m revoluzen_flow open

The backend boots on loopback, your browser opens, and you're in. Needs Python 3.11+ and Node 20+. On Windows, or for Docker, see Quick start.

The Revoluzen Flow canvas: a nine-node pipeline, Revenue by Region, open as a draft of a published pipeline, taking orders through a data-quality check and a filter, and customers through a dedupe, into a join, then a derived revenue column and an aggregation by region into a managed table Build pipelines on a canvas · 45 node types · 68 connectors · run, schedule and alert from the same place

Contents

🚀 Quick start Pick an install path
🖼 What it looks like The product, in screens
▶️ First run Install to real output in a minute
⚙️ Running it Ports, background service, cloud
💡 Why Revoluzen Flow What you get, and why it matters
🔌 Connectors An open framework, not a vendor queue
🛡 Steward Read-only pipeline health
📦 Editions OSS vs Enterprise
🔧 Install troubleshooting Every failure we know about

Quick start

Revoluzen Flow is a self-hosted server plus web app — a backend that serves a browser UI, not a desktop program.

You are Path Time
On any OS and want it to just work Docker Compose — one identical command everywhere 2–5 min
Comfortable with Python 3.11+ and Node 20+, or a contributor From source 10 min

Not available yet, because no release has been published: the one-line install, PyPI and Linux packages. They are described below for when it is.

One-line install

Linux x86_64. Installs per-user, no root. The AppImage it fetches carries its own Python runtime, so nothing needs to be on the machine first.

curl -fsSL https://raw.githubusercontent.com/revoluzen-io/revoluzen-flow/main/installer/install.sh | sh

Then revoluzen serve and open http://localhost:8001.

It resolves the latest release, verifies the download against the release's SHA256SUMS and aborts if that check fails or the file is unlisted, installs to ~/.local/share/revoluzen-flow, and links ~/.local/bin/revoluzen. It does not edit your shell profile — if ~/.local/bin is not on PATH it prints the line to add. Pin a version with REVOLUZEN_VERSION=v1.0.1, relocate with REVOLUZEN_PREFIX=/opt/rzf.

Windows and macOS are not covered by this yet, and the script will tell you so rather than fail obscurely. Revoluzen Flow does not publish unsigned Windows or macOS builds: without an EV certificate SmartScreen shows a red block dialog, and without Developer ID notarization Gatekeeper refuses to open the package at all — which stops exactly the people a one-line installer is for. Use Docker Compose or From source there until signing is in place. installer/install.ps1 is written and waiting on that.

Docker Compose

git clone https://github.com/revoluzen-io/revoluzen-flow.git
cd revoluzen-flow
cp .env.example .env            # optional — defaults work
docker compose up -d            # Revoluzen Flow only
# or:
docker compose --profile ai up -d   # Revoluzen Flow + local Ollama

Open http://localhost:8001. Upgrade later with git pull && docker compose build && docker compose up -d.

Single container instead of compose

One container is enough, but build the image first — docker run has no build step and would try to pull an image that isn't published yet:

docker build -t revoluzen/flow:1.0.1 .
docker run -d --name revoluzen-flow \
  -p 8001:8001 \
  -v revoluzen_flow_data:/data \
  -e REVOLUZEN_FLOW_DATA_DIR=/data \
  revoluzen/flow:1.0.1

PyPI

Requires Python 3.11+ (the suite is run on 3.11 and 3.13). Check first — an older Python fails with No matching distribution found:

py --version        # Windows
python3 --version   # macOS / Linux
# Windows — the py launcher avoids Python Scripts/PATH shortcut issues
py -m pip install --upgrade revoluzen-flow
py -m revoluzen_flow open
# macOS / Linux — modern macOS ships python3, not python
python3 -m pip install --upgrade revoluzen-flow
python3 -m revoluzen_flow open

revoluzen open is an optional shorthand the install creates. If it isn't found, python -m revoluzen_flow open always works — see Install troubleshooting.

Linux package

Bundles a frozen Python runtime and the compiled UI — no Python, no Node, no Docker on the target machine. After install, Revoluzen Flow registers itself as a systemd user service that starts at login and survives reboots.

Download from the latest GitHub Release:

Distro Package Install
Debian / Ubuntu 22.04+ revoluzen_flow_1.0.0_amd64.deb sudo apt install ./revoluzen_flow_1.0.0_amd64.deb
Fedora / RHEL / Alma / Rocky 9+ revoluzen-flow-1.0.0-1.x86_64.rpm sudo dnf install ./revoluzen-flow-1.0.0-1.x86_64.rpm
Any Linux (glibc 2.27+) RevoluzenFlow-1.0.0-x86_64.AppImage chmod +x ./RevoluzenFlow-*.AppImage && ./RevoluzenFlow-*.AppImage

Then open http://localhost:8001 — the service is already running.

Building these installers yourself (CI / private builds): see installer/readme.md.

From source

Requires Python 3.11+ and Node 20+. Install and run are two separate steps, and you must be inside the cloned repo — the . in pip install -e . means "the project in this folder".

git clone https://github.com/revoluzen-io/revoluzen-flow.git
cd revoluzen-flow

# 1. Build the UI (one-time). The bundle isn't committed — skip this and
#    the API runs but / serves nothing.
cd frontend && npm ci && npm run build && cd ..

# 2. Install into a venv, then run.
python -m venv .venv && source .venv/bin/activate
pip install -e .
python -m revoluzen_flow open
Windows (PowerShell) — one line at a time

&& chaining and source are not valid in Windows PowerShell:

git clone https://github.com/revoluzen-io/revoluzen-flow.git
cd revoluzen-flow

# 1. Build the UI (one-time).
cd frontend
npm ci
npm run build
cd ..

# 2. Install into a venv, then run.
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
python -m revoluzen_flow open

If Activate.ps1 is blocked by execution policy, don't fight it — call the venv's executables directly: .\.venv\Scripts\pip.exe install -e . then .\.venv\Scripts\python.exe -m revoluzen_flow open.

Where's the native Windows / macOS installer?

For a self-hosted server app, the standard way to run it on Windows or macOS is Docker Desktop — that's how comparable tools (Grafana, Metabase, Gitea, Nextcloud) ship, and it works identically everywhere. A native .exe / .pkg builds and works, but we don't publish it: unsigned, it trips Windows SmartScreen and macOS Gatekeeper with a scary dialog, and we won't hand you that. Want it anyway? Build it in one command — see installer/readme.md. Signed installers land once we have an EV certificate and Apple notarization.

What it looks like

Pipelines, projects and folders — status, schedule, alerts, contracts and last run for every pipeline, with your projects and their folders in a panel beside the list. Pick a project to see only its pipelines and its owner, and add a folder or edit the project from the same place.

The Pipelines page with the projects panel on the left and the Supply Chain project selected and opened to its two folders, Partner feeds and Stock; on the right its owner and eight pipelines, published and draft, with schedules every ten minutes, hourly, daily and one that starts when a new file arrives, two with an alert, and the managed tables each one writes

Connections — one open framework across databases, warehouses, object stores, streams and SaaS APIs, each with its own health state.

The Connections page listing seven connections — three REST APIs, a partner FTP server, a Windows file share, a Kafka stream and a SQLite database — with scope, the pipelines using each, a description and the last test: four passing, one failing and two untested

Executions — every run, its steps, rows and duration.

The Executions page filtered to one pipeline over the last 24 hours: eight Store Footfall runs, seven successful and one error with one of its three steps failed, started by the schedule or a pre-publish test, each with environment, start time, elapsed time and step count

One run, opened — runtime lineage of what actually ran, with rows in and out of each step, per-step timings, peak memory and CPU. Click any node to read the rows it produced, as a table, a schema or raw JSON, and export them. Re-run and Replay sit on the same screen.

An execution summary for Stock Value by Warehouse showing six passed steps — two sources joined, a derived stock value, an aggregate by warehouse and a managed-table sink — each with its row count and duration, with the aggregate node selected and its output rows of stock value and line count per warehouse open below the graph, exportable as CSV or JSON

Every step, with its data — open a step to see the parameters it ran with, the rows it received from upstream, and the rows it produced. Samples are captured at run time, so you are reading what the run actually did rather than re-querying a source that has since moved on.

An expanded aggregate step showing three panels: its group-by and sum and count configuration, a sample of the 1,300 rows received from the upstream derived column, and the five rows it produced — stock value and line count per warehouse, with column types

Triggers — let another application start a pipeline and pass it values. Give the pipeline an endpoint, choose how callers prove who they are, and copy the ready-to-use curl or PowerShell command.

The Triggers page with two endpoints, one checked by a signature and one by an API key, and the ready-to-use curl command for the regional-revenue endpoint — a POST to localhost:8001 with an X-API-Key header and a JSON body setting the region to EMEA — explained line by line, with the pipeline's region parameter listed below

Storage — managed parquet tables written by your pipelines.

The Managed Tables page listing 22 parquet tables across crm, finance and other schemas, each with the pipeline and version that prepared it and when it was loaded, its row count, column count, size and the pipelines that use it

Any dataset, inspected — open a table to read its rows and column types, see which pipeline produced it and which ones consume it.

The sales.orders_clean managed table opened in the dataset viewer: 34,285 rows across ten typed columns, produced by Orders Daily Load with its last successful run, consumed by two pipelines, and Preview, Schema, Profile, Tests and History tabs

Steward — a read-only reliability layer that watches for schema drift, null and duplicate spikes, connector failures and PII exposure, and tells you how many scans it has seen each one in.

The Steward findings panel open over the Pipelines page, its findings split across architecture, connector, data, governance and node checks and filtered to node findings: row counts that changed in steps that should preserve them, each with priority, severity, how many scans have seen it, and resolve, dismiss or Ask Copilot actions

Bring your own LLM — or keep it on your machine. Ten providers, two of them local. Point it at Ollama and pull a model from the list; nothing leaves the host. AI is optional throughout: turn it off and every feature falls back to a deterministic path, with the engine unchanged.

The AI provider page with AI enabled and Claude selected from ten providers, two of them local, the active provider shown as connected with its model and 37 tools, and the API key held on file rather than displayed
More screens — Execution Pool, API Explorer

Execution Pool — concurrency, what is waiting for a slot, and what each run cost in time, memory and CPU.

The Execution Pool's run history: 200 recent runs with priority, worker, status, trigger, a duration bar, start time, peak memory and CPU seconds for each

API Explorer — load a spec, send one authenticated request, assert on the response, then generate a connector from it.

The API Explorer after one GET request to a public exchange-rates API with two query parameters: an HTTP 200 response shown as a JSON tree, the choose-an-endpoint and test-it steps ticked, and generating a connector as the next step

First run

On first launch Revoluzen Flow asks you to create your account — your email and a password. This first account owns the instance.

Then open Templates → First pipeline — CSV in, CSV out → Use Template → Run. You'll see real output from a seeded sample dataset in under a minute: no Postgres, no API keys, no cloud account.

flowchart LR
  subgraph Ingest
    A[("CSV / Parquet<br/>Excel / JSON")]
    B[("Postgres · MySQL<br/>Snowflake · BigQuery")]
    C[("REST · Kafka<br/>S3 · SFTP")]
  end
  A --> T
  B --> T
  C --> T
  subgraph Transform["Transform — vectorised DuckDB"]
    T["join · aggregate · filter<br/>pivot · window · SCD2<br/>data quality · dedupe"]
  end
  T --> L{"Branch<br/>on a condition"}
  L -->|pass| S[("Managed table<br/>warehouse · S3 · CSV")]
  L -->|fail| N["Alert<br/>Slack · email"]
  S --> O["Schedule · retry · lineage<br/>run history · rollback"]

Running it

python -m revoluzen_flow open starts the backend on a free port (8001 by default, falling back if in use) and opens your browser. If the output says port 8001 was in use — using 8003 instead, open the printed URL.

python -m revoluzen_flow serve             # start on 127.0.0.1:8001, open the browser yourself
python -m revoluzen_flow serve --open      # same as `open`
python -m revoluzen_flow serve --port 9000

Health check: curl http://localhost:8001/api/health

Headless, WSL2, Docker, DevContainer or remote-SSH? open detects these automatically, skips the browser launch and prints the URL prominently so you can paste it into a browser on your host. --no-open force-skips the launch while keeping the port-fallback behaviour.

Environment variables: .env.example. Day-2 ops (upgrades, backup, DR, troubleshooting): docs/deployment.md.

As a background service

serve and open run in the foreground — fine while trying it out, but they stop when you close the terminal. For an always-on install that survives logout and reboot, register with your OS service manager. One command, every platform:

python -m revoluzen_flow install-service     # register + start it supervised
python -m revoluzen_flow service-status      # is it running?
python -m revoluzen_flow uninstall-service   # remove it (does NOT delete data)
OS What it registers Notes
Windows Scheduled Task at logon (schtasks) Runs hidden, restarts on crash — no NSSM or pywin32. 1.0.x registers with highest privileges, so run PowerShell as Administrator if you see REGISTER_FAIL: Access is denied.
macOS launchd LaunchAgent Auto-starts at login, KeepAlive restart.
Linux user-mode systemd unit systemctl --user enable --now; add loginctl enable-linger $USER to keep it running after logout.

On Docker instead? You don't need this — docker compose up -d is already detached, and the compose file's restart policy brings the container back on reboot or crash.

Deploy to cloud

Runs on any platform that takes a Docker image. Config files are in the repo root:

Platform Config Quick start
Fly.io fly.toml fly launch --copy-config
Render render.yaml New → Blueprint → connect this repo
Railway railway.toml New → Deploy from GitHub repo

Why Revoluzen Flow

Built for teams who want a local, visual ETL engine without dragging in a warehouse-first platform or a heavyweight IDE.

What you get Why it matters
DuckDB execution Joins, group-bys, pivots and aggregates run in a vectorised engine, with disk spill for larger local workloads.
Operations in the box Scheduler, endpoints so another application can start a pipeline, alerts, run history, per-step row counts, lineage view, versioning, deploy and rollback are included.
Local-first install Runs on a laptop or VM. No cloud lock-in. Telemetry is off by default and opt-in only.
Visual + code workflow Drag nodes on the canvas, use expressions for light logic, and drop into DuckDB SQL when the canvas is not enough.
Optional AI assistance Claude, OpenAI, Gemini, Ollama and OpenRouter can help with node setup, SQL and error diagnosis; deterministic fallbacks keep the app useful without an LLM.

Connectors

Revoluzen Flow ships an open connector framework, not a closed vendor queue. Current OSS includes native database and bulk-load connectors plus REST-manifest SaaS connectors, each labeled by maturity: Production, Verified, Beta, Experimental or Hidden. The picker shows stable tiers first; Experimental sits behind a toggle. See docs/connectors.md or GET /api/connectors/cert-matrix for the live matrix.

Need one that isn't shipped yet?

Path Best when
Paste an OpenAPI URL The vendor publishes an OpenAPI spec.
Paste sample API responses The API has no public spec, but you have example payloads.
Hand-author a manifest The API needs custom paging, auth or field mapping.
Request or contribute The connector should become part of the OSS catalog.

The first three live in Insights → API Explorer: load a spec (or any URL), send one authenticated request, assert on the response, then generate and save the connector — no restart, no compile step, no LLM.

No connector is Plus-gated. Every OSS manifest, node and extension path stays open. See docs/extend/build-a-connector.md for the authoring tutorial.

Steward reliability layer

Steward is a read-only observer for pipeline health. It detects duplicate sources and pipelines, connector health, schema drift, volume anomalies, data-quality threshold failures, empty node outputs, warehouse waste, governance issues and user-defined YAML rules. Findings carry occurrence counts, severity escalation, rebound detection, sanitized dismiss reasons and notification de-duplication.

See docs/steward/overview.md, docs/steward/positioning.md and docs/steward/architecture.md.

Editions

Revoluzen Flow is the open-source core for individuals and small teams — a solo, single-workspace install. Revoluzen Flow Enterprise is a commercial layer adding team workspaces, RBAC, two-gate approvals, audit logs, vault-backed credentials, sandbox, drift detection, enterprise deployment and SLA-backed support.

See edition-matrix.md for the per-feature breakdown.

Install troubleshooting

Windows: revoluzen is not recognized after install

If pip install revoluzen-flow succeeds but PowerShell says The term 'revoluzen' is not recognized, Revoluzen Flow installed correctly. Windows just cannot find the generated revoluzen.exe because Python's Scripts folder is not on PATH. This is a Windows/Python PATH setting, not a server failure.

Use the Python launcher form:

py -m pip install --upgrade revoluzen-flow
py -m revoluzen_flow open

If py is unavailable, use python instead. To confirm where it installed:

py -m pip show revoluzen-flow
py -m site --user-base

The direct command works only when the matching Python Scripts folder is on your user PATH (for example <user-base>\Scripts). After changing PATH, close and reopen PowerShell or VS Code.

Intel Macs (x86_64): openssl-sys: Could not find directory of OpenSSL installation

cryptography 49+ publishes macOS wheels for Apple Silicon only, so on an Intel Mac pip falls back to a source build needing a Rust toolchain and OpenSSL headers. Revoluzen Flow 1.0.1 caps that dependency to the last Intel-compatible release, so a current install just works.

If you are on 1.0.0 or earlier:

python3 -m pip install "cryptography<49"
python3 -m pip install --upgrade revoluzen-flow
error: externally-managed-environment

Homebrew and Debian Pythons refuse system-wide installs. Use a virtualenv:

python3 -m venv ~/revoluzen-flow-venv
source ~/revoluzen-flow-venv/bin/activate
pip install --upgrade revoluzen-flow
Corporate proxy: SSL: CERTIFICATE_VERIFY_FAILED

If pip install — or the first docker compose up build, which runs pip inside the image — fails with self-signed certificate in certificate chain, that's your network's TLS-inspecting proxy, not Revoluzen Flow. It breaks any Python install on that network. Fixes, best first:

  1. Trust your org's root CA (proper fix). Get the cert from IT, then pip config set global.cert C:\path\to\corp-ca.pem and point REQUESTS_CA_BUNDLE at the same file. For the Docker build, bake the CA into the image.
  2. Pull a prebuilt image (cleanest, once published). A single TLS handshake your Docker Desktop proxy settings already handle — no in-network pip build.
  3. Quick unblock (less strict). pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org -e .

Full install troubleshooting lives in docs/quickstart.md.

License

Apache License 2.0 — see LICENSE and NOTICE.

"Revoluzen Flow" and "Revoluzen" are trademarks of Revoluzen. See TRADEMARK.md for usage policy.

Contributing

External pull requests are paused for v1.0.0 while our Contributor License Agreement clears legal review — we won't ask you to sign a draft. Bug reports, connector and node requests, questions and design feedback are all open and wanted, and Revoluzen Flow is Apache 2.0 so forking is always yours. See CONTRIBUTING.md for the details and for how to park a fix you've already written.

CODE_OF_CONDUCT.md has the rules of the road.

Security

Found a vulnerability? See SECURITY.md. Please do not file public issues for security reports.


Documentation · Quick start · Enterprise · hello@revoluzen.io

Built and maintained by Revoluzen · Apache 2.0

Metadata

Release files for revoluzen-flow 1.0.1.dev0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for revoluzen-flow 1.0.1.dev0
File Size Uploaded Provenance Actions
revoluzen_flow-1.0.1.dev0.tar.gz 5.8 MB With provenance Details for revoluzen_flow-1.0.1.dev0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for revoluzen-flow 1.0.1.dev0
File Interpreter ABI Platform Actions
revoluzen_flow-1.0.1.dev0-py3-none-any.whl Python 3 none any Details for revoluzen_flow-1.0.1.dev0-py3-none-any.whl

Total release size: 12.1 MB

Release files / revoluzen_flow-1.0.1.dev0.tar.gz

Download URL revoluzen_flow-1.0.1.dev0.tar.gz
Size 5.8 MB
Tags Source
SHA-256 checksum
How to use checksums
efc8072837db5d3ffdde6d1ee47f6d88ff2869df64ec07118e7ac59a31876d65
BLAKE2b-256 checksum
How to use checksums
837ee6ba8ce731961ba8a8502776ce1774a69f33e971317656881986243580fb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / revoluzen_flow-1.0.1.dev0-py3-none-any.whl

Download URL revoluzen_flow-1.0.1.dev0-py3-none-any.whl
Size 6.3 MB
Tags Python 3
SHA-256 checksum
How to use checksums
4c68871c37068317c321a300d80cd55b3d0922582981d123202cd1b76266284e
BLAKE2b-256 checksum
How to use checksums
d0c8c3240f204839624e4d203b2d92f3b4fe31e31bf1303eb0b58720dde5faf3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for revoluzen-flow 1.0.1.dev0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for revoluzen_flow-1.0.1.dev0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page