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

Any of the three install artifacts works: the single-file agent, the Docker image, or a VM booted from the live ISO. For a quick local ride, the host can run on the same machine as the Nucleus.

1. Enroll it

  1. Nucleus → Hosts → Enroll: create a join token.
  2. Hand it to the agent — CLI --join, NINER_JOIN_* environment variables, or paste it into the host GUI’s Connect to Nucleus screen.
  3. The host appears in the fleet view as authorized, with its environment label, status and an open-host link.

If hosts live on other machines, make sure the Nucleus was started with a routable NINER_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, pick the host, and pick the artifact mode:

  • Source — fastest install; the host runs the generated app with its bundled Bun.
  • Executable — a single compiled binary built for the host’s OS/arch (cross-compiled by the Nucleus when needed — e.g. building linux-x64 for a Docker host from a Windows Nucleus).

The deploy:

  1. compiles the workflow (the same document you tested — niner.workflow.v1, no conversion),
  2. mints a resolve token scoped to this deployment (the app’s key to lease secrets at run start),
  3. pushes the artifact to the host, which installs, port-allocates and starts it.

3. Watch it

  • Workflows view — the workflow’s row expands to its deployments: host, status, version. The logs drawer streams the app’s output through the Nucleus.
  • Host dashboard — apps with status and uptime, the run ledger, queue stats, and the Resources tab (per-app CPU, memory, disk).
  • The app itself serves a status endpoint with health, run history and stats — the host links to it.

4. Operate it

ActionEffect
StopGraceful shutdown; the app shows stopped (not failed) and stays installed.
RestartStop + start; ~300 ms typical.
RedeployNew artifact replaces the old, same workflow identity (deployments match by workflow id, so renames don’t orphan them).
RemoveUninstalls the app from the host.

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

Checklist for real workloads

  • Started the Nucleus with a routable NINER_NUCLEUS_PUBLIC_URL? (Secrets leasing and dial-home depend on it.)
  • Proxmox/VM hosts: CPU type host (AVX2) for compiled executables.
  • 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.