Cloudless User Guide

A practical how-to for everything you can do with Cloudless today. If you can run one

command and open a browser, you can run a private mesh cloud.

1. Install & start your first node

# build from source (Go 1.22+)
git clone https://github.com/asifontheline/cloudless
cd cloudless/cloudless && go build -o cloudless ./cmd/cloudless

# start — detects a local model runtime, generates keys, prints an invite
./cloudless up

You'll see:

Console:  http://127.0.0.1:8080/          your private control panel (this machine only)
API:      http://<this-ip>:8080/v1/chat/completions (Bearer <api key>)
Add a node: cloudless up -join <secret>@<your-ip>:7946

`127.0.0.1:8080` is your admin console — open it in a browser. The **invite line** is what you

share to grow the mesh.

2. Add more machines (grow the mesh)

On a second machine (reachable over your LAN, VPN, or public IP), paste the invite:

./cloudless up -join <secret>@<first-node-ip>:7946

It enrolls (gets a certificate), joins the encrypted gossip mesh, and starts serving. Tag a

node's location so it shows on the map:

./cloudless up -location asia/india/karnataka/bengaluru

3. Use the AI (from anything)

Point any standard chat-completions client at any node:

curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer <api key>" \
  -d '{"model":"<your-model>","messages":[{"role":"user","content":"hi"}]}'

From Python (zero-dependency SDK):

from cloudless import Client
mesh = Client("http://localhost:8080", api_key="<api key>")
print(mesh.chat("Explain the mesh in one line"))

Requests route to the best healthy node and fail over automatically if one drops.

4. The console — one place for everything

Open `http://127.0.0.1:8080/`. Tabs:

Admin actions in the console need the cluster key (from `~/.cloudless/config.json`) — paste it

once on the Members page; it's stored only in your browser.

5. Common tasks (CLI + console + API all work)

TaskCLIConsoleAPI
See the mesh`cloudless status`Dashboard / Map`GET /status`
Add a member key`cloudless keys create alice`Security → Members`POST /keys`
Revoke a key`cloudless keys revoke <prefix>`Security → Members`DELETE /keys/{prefix}`
Set how much you share`cloudless share set -cpu 40 -when charging`Security → Resource Sharing`PUT /share`
Add a model`cloudless models add model.gguf`Storage → Model Commons`PUT /store`
Pull a model from peers`cloudless models pull model.gguf`Storage → Model Commons`POST /store/pull`
Verify a model`cloudless models verify model.gguf`Storage → Model Commons`GET /store/verify`
See usage`cloudless usage`Operations → Usage`GET /usage`
See who gave/used`cloudless ledger`Operations → Contribution Ledger`GET /ledger`
Cost vs cloud`cloudless savings`Operations → Cost Calculator`GET /savings`
Find idle nodes`cloudless capacity`Operations → Idle Capacity`GET /capacity`
Evict a node`cloudless nodes revoke <name>`Map → revoke`POST /revoke/{name}`
Check the audit log`cloudless audit`Security → Audit Log`GET /audit`

6. How much you share (safe by default)

Every node starts at a safe **5%** of CPU and can be tuned up to a **70%** ceiling — never

100%, so your machine stays responsive. On phones a thermal/battery guard pauses sharing if it

warms up or runs low (in build). Change it anytime:

cloudless share            # show current
cloudless share set -cpu 70 -when always   # a dedicated/idle box: turn it up
cloudless share set -cpu 0                 # stop sharing

Contribution is metered on the ledger, and you earn service in proportion to what you give.

7. Models: the commons

Add a model once, and peers can pull it from each other instead of re-downloading. Only safe

tensor formats are accepted (`.gguf`, `.safetensors`, `.onnx`) — pickle-based files are rejected

because they can execute code. Every artifact is SHA-256 verified on the way in and on demand.

8. Security you get for free

9. Contribute

You don't need to know Go. Build in any language against the open API (see

[PROTOCOL.md](https://github.com/asifontheline/cloudless/blob/main/PROTOCOL.md)); Python is

first-class. Changes flow through: branch → pull request → CI validation → review → merge queue.

Full guide: [CONTRIBUTING.md](https://github.com/asifontheline/cloudless/blob/main/CONTRIBUTING.md).

10. Troubleshooting

port 7946). A one-click overlay is in build.

Cloudless Blueprint

1. Goal

Build a decentralized platform where independent systems share compute, storage, and network resources over the internet so the system can offer cloud-style services without relying on a single commercial cloud provider. AI should be part of the platform’s capabilities, but not part of the name.

This system is not just an intranet, extranet, or community network. It is a shared infrastructure platform that combines distributed compute, model hosting, orchestration, replication, and trust across community hardware.

1.1 Alternate Names

2. Core Principles

2.1 Governing and Guiding Principles

3. Architecture

A. Node federation
B. Work orchestration
C. Model distribution
D. Storage and data
E. Network layer

4. Governance and Agreements

5. Security and Trust

6. Suggested Implementation Stack

Licensing rule: only OSI-approved open-source components (Apache-2.0/MIT/BSD/MPL/GPL) — no BUSL or source-available software (excludes Nomad, Consul, Vault, ZeroTier) and no proprietary SaaS control planes (excludes Tailscale coordination).

7. Practical Phases

1. Prototype

2. Add discovery

3. Expand

4. Governance

8. Reality Check

9. Cloud Feature Replication

To make this the cheapest ever solution while still matching public cloud capabilities, the plan must replicate these cloud principles:

10. Community Hardware Strategy

Community and low-cost hardware are the backbone of this plan. Key design choices:

10.0 Mobile Devices as Nodes (Epic J)

Phones and tablets are the most common, hand-carried commodity hardware — first-class nodes, not an afterthought:

10.0.1 Resource Cap — Safe Default, User's Discretion (hard rule)

Contribution must never be disruptive, and how much to give is always the contributor's choice:

10.1 Resource Sharing Controls and Reciprocity

Members stay in control of what they give, and what they give determines what they get:

10.1.1 The Portal — one stop to use and contribute

After passwordless (passkey) sign-in, the embedded web console is the member's single portal:

10.2 Community Node Tracking and the Network Map

Every node in the community mesh is tracked and visible:

10.3 Locality-Aware Redundancy

Failure tolerance is built around geography:

11. Rule Engine Rules

The rule engine should enforce replication, monitoring, and failover for reliable services on community hardware.

12. Example Outcome

A working “cloudless AI” system can provide:

12. Architecture Diagram

                 +---------------------------+
                 |    Client / API Layer     |
                 |  - User apps              |
                 |  - Web/mobile UI          |
                 |  - External integration   |
                 +------------+--------------+
                              |
                              v
                 +---------------------------+
                 |   Federation Gateway      |
                 |  - Request routing        |
                 |  - Task validation        |
                 |  - Policy enforcement     |
                 +------------+--------------+
                              |
          +-------------------+-------------------+
          |                                       |
          v                                       v
+----------------------+               +----------------------+
|  Node Discovery      |               |   Task Orchestration |
|  - DHT / bootstrap   |               |  - Scheduler         |
|  - Peer discovery    |               |  - Work assignment   |
|  - Node registry     |               |  - Failure retry     |
+----------+-----------+               +----------+-----------+
           |                                      |
           v                                      v
+-------------------------------------------------------------+
|                       Federated Node Mesh                    |
|  +----------------+   +----------------+   +----------------+ |
|  | Node A         |   | Node B         |   | Node C         | |
|  | - Agent        |   | - Agent        |   | - Agent        | |
|  | - Local cache  |   | - Local cache  |   | - Local cache  | |
|  | - AI runtimes  |   | - AI runtimes  |   | - AI runtimes  | |
|  | - Storage      |   | - Storage      |   | - Storage      | |
|  +-------+--------+   +-------+--------+   +-------+--------+ |
|          |                    |                    |          |
|          +-----+    +---------+----+    +----------+          |
|                |    |              |    |                     |
+-------------------------------------------------------------+
           |                    |                    |
           |                    |                    |
           v                    v                    v
+----------------+   +----------------+   +----------------+
| Model Storage  |   | Data Storage   |   | Security /     |
| - IPFS / DHT   |   | - P2P cache    |   |   Identity     |
| - Model shards |   | - Local sync   |   | - TLS / mTLS   |
+----------------+   +----------------+   +----------------+

Cloudless: A Community-Powered Decentralized Infrastructure

Abstract

This paper proposes a decentralized platform that uses community-contributed compute, storage, and network resources to deliver cloud-like services, including AI, without relying on a centralized public cloud provider. The platform prioritizes privacy, low-cost hardware, and cooperative governance, while providing replication, failover, and orchestration for best-in-class reliability.

1. Introduction

Public cloud providers offer scalable services, but they are often expensive, proprietary, and raise privacy concerns. We present a new alternative: a federated compute infrastructure built from community hardware and shared systems. This platform is not an intranet, extranet, or traditional community network; it is a general-purpose distributed fabric with AI as one first-class capability, integrating model hosting, task scheduling, data caching, and trusted execution.

1.1 Problem Statement
1.2 Contribution

2. Related Work

2.1 Public Cloud AI
2.2 Federated Learning and Distributed AI
2.3 Decentralized Compute and Storage
2.4 Distinction

This work differs by combining distributed compute, model distribution, and AI service orchestration into a single community-driven platform with built-in failover and privacy-first processing.

3. System Architecture

A high-level architecture of the platform includes:

3.1 Node Federation

Each participant runs an agent that advertises compute, storage, and AI runtimes. Discovery is handled through DHT, bootstrap peers, and optional directories.

3.2 Work Orchestration

A decentralized scheduler assigns inference, training, and preprocessing tasks. Containerized or sandboxed workloads run on nodes with local caching and lightweight runtime support.

3.3 Model Distribution

Models are shared via a content-addressed distributed network. Nodes cache models locally and may store sharded or replicated copies to reduce bandwidth.

3.4 Storage and Data

Shared artifacts are stored in peer-to-peer storage systems. Sensitive user data remains local unless explicit consent is granted.

3.5 Network Layer

The platform uses encrypted P2P communication, NAT traversal, and optional mesh overlays to connect nodes securely.

4. Governing and Guiding Principles

5. Rule Engine

The rule engine enforces service behavior:

6. Replication and Failover Strategy

6.1 Compute Replication
6.2 Data and Model Replication
6.3 Failure Handling

7. Community Hardware Strategy

The platform is designed for heterogeneous, inexpensive hardware. Key aspects include:

7.1 Resource Governance and Reciprocity

Participation is voluntary and bounded: each member declares how much CPU, IO, disk, and bandwidth their node shares, and when. The agent enforces these declarations locally. Contribution is metered in a cooperative ledger, and service entitlement is reciprocal — proportional to contribution, with community-set minimum floors to keep the mesh inclusive. This replaces cloud billing with a balance of give and take.

7.2 Geo-Hierarchical Topology and Observability

Nodes carry hierarchical locality labels (continent/country/state/city/village). The platform maintains a live network map — healthy and failed nodes visible at every level — giving the community a shared operational picture across continents without any central NOC.

7.3 Locality-Aware Redundancy

Replication and routing are locality-aware: requests prefer nearby nodes, replicas are spread across localities, and failover widens outward through the hierarchy. Partitioned localities continue to serve locally, rejoining the wider mesh when connectivity returns.

8. Evaluation Plan

A strong paper requires evaluation. Suggested experiments:

9. Conclusion

This paper outlines a practical path toward a community-powered AI infrastructure that matches core cloud capabilities while avoiding centralized dependency. The platform aims to deliver low-cost, private, reliable AI services using distributed, cooperative hardware.

10. Future Work

References

CloudLess · Apache-2.0 · published from the open repository.