clusterflux-public/docs/getting-started.md

Getting started

This guide uses the hosted coordinator. For your own coordinator, complete Self-hosting first and then return to the node and run steps.

1. Install the commands

cargo install --path crates/clusterflux-cli --bin clusterflux
cargo install --path crates/clusterflux-node --bin clusterflux-node
cargo install --path crates/clusterflux-dap --bin clusterflux-debug-dap

On NixOS or another system with Nix, the equivalent package is available with nix profile install .#clusterflux-tools.

Install rootless Podman on each Linux node that will execute container-backed environments.

2. Sign in and select your hosted project

clusterflux login --browser
clusterflux auth status
clusterflux project list
clusterflux project select <hosted-project-id>

The browser flow is owned by the configured Authentik identity provider. The CLI stores an opaque Clusterflux session, not provider authorization codes or provider tokens. Hosted login creates or links your single project; hosted admission rejects additional project creation.

3. Enroll and start a node

Create a short-lived grant:

clusterflux node enroll --project-id <hosted-project-id> --json

Create the local node identity and exchange the grant once:

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

Clusterflux creates and stores the node key locally with restricted permissions. The enrollment grant is not needed again. Stop and restart the worker with the same stored identity:

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

Supplying --public-key and CLUSTERFLUX_NODE_PRIVATE_KEY is an advanced option for nodes whose key material is managed externally. Check server-derived liveness with:

clusterflux node list
clusterflux node status workstation

4. Inspect and run a bundle

A project contains clusterflux.toml, Rust workflow source, and any declared environments under envs/. Task arguments and handles use portable canonical representations; they are not host pointers or shared process memory.

clusterflux bundle inspect --project .
clusterflux run --project . build

From this checkout, the complete source-to-task-to-artifact path is:

clusterflux bundle inspect --project examples/hello-build
clusterflux run --project examples/hello-build build
clusterflux artifact list --process <process-id>
clusterflux artifact download <artifact-id> --to ./hello-clusterflux
chmod +x ./hello-clusterflux
./hello-clusterflux

The workflow snapshots examples/hello-build, starts its compile task in the network-disabled Linux execution environment, and retains the real static executable returned by that task.

Choose another entrypoint by replacing build. Clusterflux rejects an oversized or invalid bundle before it creates the virtual process.

5. Inspect tasks and output

clusterflux process list
clusterflux process status
clusterflux task list
clusterflux logs
clusterflux artifact list

A failed task configured with AwaitOperator remains visible as awaiting action. Restart it as a new attempt under the same logical task identity:

clusterflux task restart <task-id> --process <process-id> --yes

examples/recovery-build demonstrates this without a synthetic trap. It starts two instances of build_lane; one completes while the other runs a command that exits with status 23. Edit that command to produce the recovering output, then restart the failed task. Its original join resolves from the replacement attempt.

6. Debug in VS Code

Open the project in VS Code and start Clusterflux: Launch Virtual Process. Set a breakpoint on a generated probe location and use Threads, Stack, Variables, Continue, Pause, and Restart.

Breakpoints remain unverified until the coordinator installs them. Thread IDs are stable for an exact logical task instance across snapshot updates and retry attempts. Observer reconnect diagnostics do not manufacture stopped events, and Continue succeeds only after the coordinator acknowledges resume.

A fully frozen Debug Epoch gives a consistent all-participant view. If a participant cannot freeze within five seconds, the adapter reports a partial epoch. You may inspect frozen participants, but values across running and frozen tasks are not a consistent global snapshot. Continue resumes only participants that acknowledged the freeze.

7. Download an artifact

clusterflux artifact list --process <process-id>
clusterflux artifact download <artifact-id> --to ./output.bin --max-bytes 67108864

The command opens a scoped, expiring download and verifies the artifact digest. It fails if the retaining node is stale, the bytes were garbage collected, the digest or size changed, or policy cannot reserve the transfer.