Deploy to a host

You have a workflow that tests green. Time to make it someone’s job — a host’s.

0. Have a host

You probably already do. The Nucleus supervises a host of its own: it starts with the Nucleus, enrols itself over loopback, and appears in Hosts as Built-in host — no join token, no configuration. Deploy to it exactly as you would to any other host, and skip straight to step 2.

Add a separate host when you want workflows executing on a machine other than the one the Nucleus is on. Any of the host install options works — the Docker image, a Proxmox LXC container, the live ISO appliance, or a bare single-file build. They all end at the same join flow below.

1. Enroll it

Nucleus → Hosts → Join token: generate one. It is single-use, the value is shown only once (the Nucleus stores a hash), and it expires on the window you pick — 15 minutes to 24 hours.
Hand it to the agent — the dialog gives you a copyable one-liner (flowdrome-host --join <nucleus-url> --token <token>), or set FLOWDROME_JOIN_URL / FLOWDROME_JOIN_TOKEN, or paste the Nucleus URL and the token into the Connect panel on the host’s own dashboard.
The host appears in the fleet view as authorized, with its environment label, status, version, last-seen time and an open-host link.

If hosts live on other machines, make sure the Nucleus was started with a routable FLOWDROME_NUCLEUS_PUBLIC_URL — that URL is baked into deployments as the dial-home address.

2. Deploy the workflow

From the workflow (Studio toolbar or the Workflows view), choose Deploy and pick the host. The host runs the workflow on its shared embedded engine (the same engine Studio tests with), so there is nothing to compile and no artifact mode to choose.

An install has to be self-contained, so the Nucleus first works out the workflow’s whole dependency closure — every sub-workflow it calls, and the variables, credentials and tables that it and they need:

Anything missing stops the deploy and names it (“create the missing sub-workflows, or wire the variables/credentials in Admin, then deploy again”). Better a refusal here than a workflow that fails on its first real run because a credential was never on this Nucleus.
Anything it brings along is shown for confirmation — sub-workflows are embedded to run inline (they never appear as separate deployments), tables and interface pages are listed with the versions this deploy will freeze.

Then the deploy:

takes the document you tested (flowdrome.workflow.v1, no conversion) with its sub-workflows inlined, and stamps it with the workflow’s saved version and deploy time,
mints a resolve token scoped to this deployment (the host’s key to lease this workflow’s secrets at run start),
pushes it to the host, which persists the deploy envelope and starts serving the workflow’s real triggers immediately,
pins the table and interface versions this deployment serves against — editing the live ones afterwards mints a new version and shows up as drift until you redeploy.

Deploying onto a host that already serves this workflow is a replace, and it says so by name and by version before it does anything: an active deployment is stopped, replaced and started again; one you had deliberately stopped is replaced and left stopped.

3. Watch it

Workflows view — the workflow’s row expands to its deployments: host, status, and a version badge — teal vN when the deployment runs the current saved version, orange when a newer save exists (drift you can see). The logs drawer tails the deployment’s stdout/stderr through the Nucleus.
Host console — the fleet’s expanded host row, and the same component on the host’s own dashboard. One line per workflow: status, served version, Endpoints, when it was installed, last started and last ran. Expand a row for its performance strip — throughput, latency, errors, memory, CPU over a window you pick. Runs opens the full run inspector (the same Runs view Studio uses for a test run) and Definition shows what the deployed document actually is, secrets masked.
Endpoints are click-to-copy, and the address is rewritten to one you can actually paste: the Nucleus’s built-in host advertises loopback (correct for the Nucleus calling it on the same box, useless on your laptop), so the panel substitutes the address you are browsing the Nucleus on and keeps the host’s port — http://<your-nucleus-address>:4820/…, not 127.0.0.1.
Rollback — restore an older version from the workflow’s history and the rocket action redeploys it to every host currently serving that workflow, in one step.

4. Operate it

Action	Effect
Pause	Keeps the deployment and its live triggers, but gates firing — in-flight runs park at their next node, webhooks answer `503`, schedules and pollers skip.
Resume	Un-gates it; paused runs continue where they stopped.
Stop	Tears the live triggers down — nothing fires — while the deployment stays installed and listed. It shows stopped, not failed.
Start	Re-arms the triggers; new runs begin fresh.
Redeploy	Deploy again from the workflow: the new document replaces the old under the same workflow identity (deployments match by workflow id, so renames don’t orphan them).
Remove	Deletes the deployment from the host for good — unlike Stop, there is nothing left to start.

Stop/start and pause/resume both persist across a host restart, so a deployment you stopped stays stopped.

Triggers behave per the production trigger model: real triggers serve continuously, Inject fixtures are inert, Manual makes the deployment a run-once job.

Checklist for real workloads

Started the Nucleus with a routable FLOWDROME_NUCLEUS_PUBLIC_URL? (Secrets leasing and dial-home depend on it.)
Proxmox/VM hosts: CPU type host — the engine worker’s Bun build needs AVX2, and a default kvm64/x86-64-v2-AES vCPU kills it at launch with SIGILL (exit 132). LXC containers use the node’s real CPU, so this doesn’t apply there.
Credentials referenced by the workflow exist and are connected (OAuth2 ones show green).
The recovery lane is wired if this workflow should page you when it fails — error handling.