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 create a project

clusterflux login --browser
clusterflux auth status
clusterflux project init   --new-project my-project   --name "My Project"   --yes
clusterflux project select my-project

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.

3. Enroll and start a node

Create a short-lived grant:

clusterflux node enroll --project-id my-project --json

Generate a node key pair using your normal secret-management tooling. Exchange the grant once:

clusterflux node attach   --project-id my-project   --node workstation   --enrollment-grant "$ENROLLMENT_GRANT"   --public-key "$NODE_PUBLIC_KEY"   --json

Start the worker from the project directory with its private key supplied through protected environment or credential storage:

CLUSTERFLUX_NODE_PRIVATE_KEY="$NODE_PRIVATE_KEY" clusterflux-node   --coordinator https://clusterflux.michelpaulissen.com   --tenant "$TENANT"   --project-id my-project   --node workstation   --public-key "$NODE_PUBLIC_KEY"   --project-root "$PWD"   --worker   --emit-ready

The enrollment grant is not needed again. Stop and restart the worker with the same key identity. 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/".

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 the normal Threads, Stack, Variables, Continue, Pause, and Restart controls.

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.

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.