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

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.michelpaulissen.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

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

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.

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.