clusterflux-public/docs/nodes.md

Nodes

Your node runs real commands and retains real output bytes. Enroll it once, then restart it with the same public-key identity.

Enroll

clusterflux node enroll --project-id <project-id> --json
clusterflux node attach \
  --project-id <project-id> \
  --node workstation \
  --enrollment-grant "$ENROLLMENT_GRANT"

Treat the enrollment grant as a short-lived secret. It is exchanged once and is not a worker credential. By default, clusterflux node attach creates and stores a local node key with restricted permissions. Use an explicit --public-key with CLUSTERFLUX_NODE_PRIVATE_KEY only when external secret management owns the key pair.

Run the worker

clusterflux-node \
  --coordinator https://clusterflux.lesstuff.com \
  --tenant "$TENANT" \
  --project-id <project-id> \
  --node workstation \
  --project-root "$PWD" \
  --worker \
  --emit-ready

Start the worker from the project directory when tasks need a local checkout. The worker reports detected command, container, source, VFS, environment, OS, and architecture capabilities. Use clusterflux node attach --cap <capability> only when detection needs an explicit override.

Liveness

clusterflux node list
clusterflux node status workstation

The coordinator marks a node stale after its accepted heartbeat age exceeds the configured threshold. Stale nodes are excluded before placement and before a retained-node download link is created.

Local source

A bind-mounted local checkout is fast and avoids transferring the repository, but it is non-hermetic: uncommitted changes, ignored files, and concurrent editor writes can affect the command. Use a content-addressed source snapshot when reproducibility matters.

Revoke

clusterflux node revoke workstation

Revocation removes the node identity and its live descriptor. Subsequent signed requests fail. Artifacts retained only by that node become unavailable unless you explicitly synchronized them elsewhere.