eb1077f380
Source commit: 09ca780bd67a00467e78139cf38466b8201b66ca Public tree identity: sha256:2f744c260b5fc2cf074ad9129f97f87f03714902e5b9fe174128afdc342ec2d0
107 lines
3.9 KiB
Markdown
107 lines
3.9 KiB
Markdown
# 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
|
|
portable 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.
|
|
|
|
## Build a real executable
|
|
|
|
The primary example is intentionally small: [hello-build](examples/hello-build)
|
|
snapshots its source project, spawns one container-backed compile task, and
|
|
publishes the resulting executable as a retained artifact.
|
|
|
|
~~~bash
|
|
clusterflux bundle inspect --project examples/hello-build
|
|
clusterflux run --project examples/hello-build build
|
|
clusterflux artifact list --process <process-id>
|
|
clusterflux artifact download <artifact-id> --to ./hello-clusterflux
|
|
chmod +x ./hello-clusterflux
|
|
./hello-clusterflux
|
|
~~~
|
|
|
|
The final command prints `hello from a real Clusterflux build`. The source uses
|
|
only the public SDK path: current-project snapshot, `spawn!`, `Command::run`, and
|
|
artifact publication. See [recovery-build](examples/recovery-build) for two
|
|
same-definition task instances, a real command failure, and operator restart.
|
|
|
|
## 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 auth status
|
|
clusterflux project list
|
|
clusterflux node enroll --project-id <hosted-project-id> --json
|
|
clusterflux node attach --project-id <hosted-project-id> --node workstation \
|
|
--enrollment-grant "$ENROLLMENT_GRANT"
|
|
~~~
|
|
|
|
The attach command creates and stores a local node key by default, then exchanges
|
|
the short-lived grant once. Start `clusterflux-node --worker` from the project
|
|
directory. See [Nodes](docs/nodes.md) for the complete sequence and the advanced
|
|
explicit-key option.
|
|
|
|
Choose an entrypoint and run it:
|
|
|
|
~~~bash
|
|
clusterflux bundle inspect --project examples/hello-build
|
|
clusterflux run --project examples/hello-build build
|
|
~~~
|
|
|
|
Inspect the result:
|
|
|
|
~~~bash
|
|
clusterflux process status
|
|
clusterflux task list
|
|
clusterflux logs
|
|
clusterflux artifact list
|
|
# Use the `artifact` value returned by the list command, for example:
|
|
clusterflux artifact download hello-clusterflux-4f61c2... --to ./hello-clusterflux
|
|
~~~
|
|
|
|
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 model](docs/security.md)
|
|
- [Release candidates](docs/releases.md)
|
|
- [Security reporting](SECURITY.md)
|