clusterflux-public/README.md

Clusterflux

Clusterflux runs a Rust-defined workflow as one distributed virtual process. A coordinator hosts the async main, while attached nodes execute Wasm tasks, rootless containers, and native commands. Tasks exchange canonical values and typed handles instead of sharing host memory.

Start with Getting started. It takes you through authentication, project setup, node enrollment, a run, debugging, task restart, and artifact download.

What you get

• One virtual process with distinct task instances and restart attempts.
• Bundle-declared environments resolved by digest.
• Native work only on nodes you attach.
• Metadata-first artifacts whose bytes remain on retaining nodes by default.
• VS Code debugging backed by coordinator task and attempt snapshots.
• Full and partial Debug Epochs with explicit consistency status.
• Human Authentik sessions plus scoped public-key identities for agents and nodes.
• A public coordinator, node runtime, CLI, SDK, and DAP adapter for self-hosting.

Install from this checkout

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

Rootless Podman is required on Linux nodes that build or run a declared Containerfile environment. Install VS Code when you want the graphical debug workflow.

First run

For the hosted service:

clusterflux login --browser
clusterflux project init --new-project my-project --name "My Project" --yes
clusterflux node enroll --project-id my-project --json

Use the returned short-lived enrollment grant once with "clusterflux node attach", then start "clusterflux-node --worker" from the project directory. See Nodes for the complete sequence.

Choose an entrypoint and run it:

clusterflux bundle inspect --project examples/launch-build-demo
clusterflux run --project examples/launch-build-demo build

Inspect the result:

clusterflux process status
clusterflux task list
clusterflux logs
clusterflux artifact list
clusterflux artifact download app.txt --to ./app.txt

To run your own coordinator instead, follow Self-hosting. The hosted website is not required for self-hosted projects.

Documentation

• Getting started
• Architecture
• Nodes
• Environments
• Artifacts
• Debugging
• Task ABI
• Self-hosting
• Security