# Getting started This guide uses the hosted coordinator. For your own coordinator, complete [Self-hosting](self-hosting.md) first and then return to the node and run steps. ## 1. Install the commands ~~~bash 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 ~~~bash clusterflux login --browser clusterflux auth status clusterflux project list clusterflux project select ~~~ 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: ~~~bash clusterflux node enroll --project-id --json ~~~ Create the local node identity and exchange the grant once: ~~~bash clusterflux node attach \ --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: ~~~bash clusterflux-node \ --coordinator https://clusterflux.michelpaulissen.com \ --tenant "$TENANT" \ --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: ~~~bash 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. ~~~bash clusterflux bundle inspect --project . clusterflux run --project . build ~~~ From this checkout, the complete source-to-task-to-artifact path is: ~~~bash clusterflux bundle inspect --project examples/hello-build clusterflux run --project examples/hello-build build clusterflux artifact list --process clusterflux artifact download --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 ~~~bash 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: ~~~bash clusterflux task restart --process --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 ~~~bash clusterflux artifact list --process clusterflux artifact download --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.