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

~~~bash
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:

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

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

~~~bash
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:

~~~bash
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:

~~~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/".

~~~bash
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

~~~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 <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

~~~bash
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.