# 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](docs/getting-started.md). 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

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

~~~bash
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](docs/nodes.md) for the complete sequence.

Choose an entrypoint and run it:

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

Inspect the result:

~~~bash
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](docs/self-hosting.md).
The hosted website is not required for self-hosted projects.

## Documentation

- [Getting started](docs/getting-started.md)
- [Architecture](docs/architecture.md)
- [Nodes](docs/nodes.md)
- [Environments](docs/environments.md)
- [Artifacts](docs/artifacts.md)
- [Debugging](docs/debugging.md)
- [Task ABI](docs/task-abi.md)
- [Self-hosting](docs/self-hosting.md)
- [Security](docs/security.md)