Install

A working Flowdrome setup is one Nucleus (the control plane, with Studio embedded) plus one or more hosts (the machines that execute workflows). For a first ride you can run both on the same machine.

Default ports: 48170 for the Nucleus, 48150 for a host. First boot creates an Admin login of admin / admin — change it immediately (the console warns you until you do).

Run the Nucleus

Option A — Docker

npm run docker:build (from a repo checkout) produces two images — flowdrome/nucleus (the control plane) and flowdrome/host-agent (the data plane) — plus portable tarballs under dist/docker/ you can docker load on any server. Run the Nucleus:

docker run -d -p 48170:48170 -v flowdrome-nucleus-data:/data flowdrome/nucleus:latest

First boot seeds admin / admin (override with -e FLOWDROME_BOOTSTRAP_USER / -e FLOWDROME_BOOTSTRAP_PASSWORD). All state lives on the /data volume.

Option B — from source

The Nucleus is a .NET service with the Studio UI embedded. From a checkout of the Flowdrome repository:

# prerequisites: Node 22+, Bun, and the .NET 10 SDK
npm install
npm run build
dotnet run --project core/Flowdrome.Control

Open http://localhost:48170, sign in as admin / admin, and change the password under Admin → Users.

A fresh Nucleus starts empty. To have something real to open before you build anything, seed the Node Demos folder — a runnable example workflow for every node in the catalog, organized by category — from a repo checkout: npm run seed:node-demos (or npm run seed:all to include the AI demo set) against your running Nucleus.

Useful environment variables:

Add a host

A host is a single self-contained agent. Pick the artifact that fits the machine; all four end at the same join flow (connect the host to your Nucleus with a join token).

Option A — Docker image

The same npm run docker:build that builds the Nucleus image also produces flowdrome/host-agent:latest (slim .NET base, non-root) with the engine worker embedded, plus a portable tarball under dist/docker/. Move the tarball to any server with Docker and load it:

docker load -i flowdrome-host-agent_<sha>.tar.gz
docker run -d -p 48150:48150 -v flowdrome-data:/data flowdrome/host-agent:latest

The image carries everything a host needs to serve deployed workflows — the agent, the embedded engine, and the compiled worker. No Node, Bun, or .NET install on the server.

Option B — the live ISO appliance (Proxmox / any VM)

npm run iso:build

This builds dist/iso/flowdrome-host-live-<sha>.iso (~321 MB, Debian-based live image). The ISO is the operating system:

• Boot from it every time — there is no installer and no install step. Keep the ISO attached; a freshly booted VM is a host in seconds.
• Persistence by disk adoption. At boot the appliance looks for a filesystem labelled FLOWDROME_DATA and mounts it as the host’s data directory — it never reformats it. If none exists, the first provably blank disk (no filesystem signatures, no partitions) is formatted once and labelled FLOWDROME_DATA. With no data disk at all, the host runs ephemeral and the console banner says so — add a blank virtual disk to keep state.
• The OS layer is immutable across reboots. Anything outside the data disk — including a changed root password — does not survive a reboot. Only FLOWDROME_DATA persists. Upgrading a host = swapping the ISO and rebooting; the data disk carries the identity and state forward.
• On Proxmox set the VM CPU type to host: the host’s engine worker is compiled with Bun’s standard x64 build, which requires AVX2. A default kvm64-class vCPU kills it at launch (exit 132).

The console shows the host’s URL on boot (e.g. http://10.1.1.112:48150).

Option C — Proxmox LXC container

Every image build also emits Proxmox CT templates (or build them alone with npm run lxc:build): dist/lxc/flowdrome-host-lxc_<ver>_amd64.tar.gz and a nucleus twin. Upload one to your Proxmox storage (web UI → CT Templates, or drop it into /var/lib/vz/template/cache/), then:

pct create 210 local:vztmpl/flowdrome-host-lxc_<ver>_amd64.tar.gz \
  --hostname flowdrome-host --memory 1024 --cores 2 \
  --mp0 local-lvm:8,mp=/data \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp --start 1

The container boots Debian 12 + systemd with the agent supervised as flowdrome.service and all state under /data. The --mp0 line puts /data on its own volume — do this on day one: it makes the data outlive any individual container. Unprivileged containers work; --password / --ssh-public-keys behave like any stock Debian template. Because an LXC container uses the node’s real CPU, the AVX2 concern from the VM path doesn’t apply — no CPU-type fiddling.

Upgrading — two paths, both keeping /data intact:

• In place (simplest): the template tarball is also the upgrade artifact. Get the newer one into the container and run the baked-in helper — it swaps /app and restarts the service:

  pct push 210 flowdrome-host-lxc_<newver>_amd64.tar.gz /root/upgrade.tar.gz
  pct exec 210 -- flowdrome-upgrade /root/upgrade.tar.gz     # or: flowdrome-upgrade https://…/flowdrome-host-lxc_<newver>_amd64.tar.gz

• Recreate (container-as-cattle): create a new CT from the new template, move the data volume over, drop the old one — possible because /data is a mount point:

  pct create 211 local:vztmpl/flowdrome-host-lxc_<newver>_amd64.tar.gz --hostname flowdrome-host …
  pct move-volume 210 mp0 --target-vmid 211 --target-volume mp0
  pct destroy 210 && pct start 211

Option D — bare single file

pwsh scripts/publish-host.ps1 -Rid linux-x64   # or win-x64, osx-arm64, …

One self-contained executable (~58 MB on Windows, ~72 MB on Linux) with the host dashboard embedded. No .NET install needed on the target. Run it under your init system of choice.

Connect the host to the Nucleus

In the Nucleus go to Hosts → Enroll, create a join token, and give it to the agent — via the CLI (--join), environment (FLOWDROME_JOIN_*), or the host GUI’s Connect to Nucleus screen. Once authorized, the host appears in the fleet view and can receive deployments.

Back up & restore

Admin → Backup exports the entire Nucleus as one JSON file — every workflow with its full version history, folders, tags, variables, credentials, users, the host registry and settings — and restores it onto any Nucleus for a near-exact copy of the system. Secrets travel decrypted in the file (that’s what lets it restore onto a fresh install with a different data key; they’re re-encrypted on import), so guard the backup like the vault itself. Restore replaces everything except active logins — the admin doing it stays signed in.

Next

Build your first workflow →