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:
- **Dashboard** — live nodes, health, latencies, recent routes.
- **Map** — every node by locality (green = up, red = down), expandable continent → village.
- **Cloud AI / Storage / Compute / Data** — the service catalog.
- **Operations** — Usage & quotas, Contribution ledger, Cost calculator, Idle capacity.
- **Security** — Members & API keys, Resource sharing, Audit log, (passwordless sign-in, in build).
- **Features** — every capability with its status and issue link.
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)
| Task | CLI | Console | API |
| 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
- Encrypted, authenticated gossip; cluster CA with mutual-TLS between nodes.
- Node revocation: evict a machine and its certificate is refused mesh-wide.
- Tamper-evident audit log of every admin action.
- Data stays on your hardware; nothing is sent to a vendor.
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
- **"no local runtime detected"** — start a local inference runtime first, or `-backend <url>`.
- **A peer won't join** — the first node must be reachable (LAN, VPN, public IP, or forwarded
port 7946). A one-click overlay is in build.
- **Passkeys** — passwordless sign-in is in build; today the console uses the cluster key.
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
- Community Mesh
- Decentralized Fabric
- Edge Federation
- Peer Grid
- Distributed Commons
- Open Mesh
- Collaborative Network
- Community Cloud
- Federated Network
- Local Grid
- Mesh Platform
- Edge Intelligence Network
- Cooperative Fabric
- Autonomous Fabric
2. Core Principles
- Decentralized federation: no central vendor controls the system
- No masters: as the network grows there are no privileged or central nodes — coordination is by gossip among equals; information is scattered across the mesh and retrievable from anywhere; there is no single point to capture, fail, or shut down
- Open protocols: common APIs and data formats
- Open architecture, polyglot by design: a stable language-agnostic API is the extension surface; users and contributors build and extend in any language — Python first-class alongside Go, plus JS/TS and WASM/subprocess plugins — never locked to one language
- Resource sharing: participants contribute CPU/GPU, storage, and bandwidth
- Open-source software: avoid proprietary lock-in
- Privacy and security: encrypt data in transit and at rest
- Incentive alignment: voluntary or credit-based cooperation
2.1 Governing and Guiding Principles
- Manageable via web: every node embeds a web console; all administration possible from a browser
- Zero-friction setup: onboarding a node is one command with auto-detection and generated defaults; setup time is a first-class cost to minimize
- Prioritize low-cost community compute over rented infrastructure
- Keep sensitive data local and enforce privacy-first processing
- Design for community-native participation and cooperative ownership
- Replicate only what matters to stay efficient and lightweight
- Optimize workloads for heterogeneous, low-cost hardware
- Use reputation and trust to reward reliable nodes and services
- Build resilience through decentralization, redundancy, and automatic failover
- Maintain open interoperability with standard model formats and APIs
- Serve customers who value cost control, privacy, and decentralized infrastructure
3. Architecture
A. Node federation
- Each participant runs a local node agent
- Nodes discover each other through:
- Distributed hash table (DHT)
- Bootstrap/rendezvous peers
- Optional lightweight directory service
- Nodes advertise:
- available CPU/GPU
- memory
- storage
- network bandwidth
- supported AI runtimes
B. Work orchestration
- A decentralized scheduler assigns tasks to available nodes
- Tasks include:
- model inference
- training/fine-tuning
- data preprocessing
- Use containerized workloads or sandboxed processes
- Lightweight orchestration alternatives:
- Nomad / HashiCorp ecosystem
- custom P2P scheduler
- edge-focused orchestrators
C. Model distribution
- Store models in a distributed content-addressed network
- Use open models in interoperable formats:
- ONNX
- GGUF
- open weights from community repositories
- Nodes cache models locally to reduce repeated downloads
- Large models can be split into shards or served from nearby peers
D. Storage and data
- Use decentralized storage for shared artifacts:
- IPFS / libp2p file system
- peer-to-peer object stores
- Keep private data local unless explicit permission is granted
- Share only computed outputs or sanitized summaries
E. Network layer
- Peer-to-peer communications with:
- TLS encryption
- NAT traversal / hole punching
- VPN or mesh overlay if needed
- Optimize for low bandwidth:
- model quantization
- delta updates
- local caching
4. Governance and Agreements
- Define an agreed protocol for:
- node onboarding
- resource advertising
- task acceptance
- failure handling
- Establish trust via:
- node reputation
- signed identities
- mutually agreed policies
- Use a simple credit or reputation system to prevent abuse
- Optionally use a distributed ledger or signed logs for audit
5. Security and Trust
- Human sign-in is passwordless by default: passkeys (WebAuthn/FIDO2) — device fingerprint/face/PIN, credential never leaves the device, phishing-resistant, with multi-device enrollment, per-device revocation, and a one-time recovery code (the cluster key remains for automation only)
- Authenticate nodes before tasks are accepted
- Run untrusted workloads in sandboxes / containers
- Encrypt all communication (membership, service, and overlay layers)
- Encrypt all data at rest on every node with a rotating key hierarchy (root → cluster → node → artifact)
- Data Guard: classify data (private/group/public, private by default), enforce locality (private data never leaves its node, group data never leaves the mesh), default-deny workload egress, audit every data movement, crypto-shred on delete
- Limit access to local data
- Accept only vetted open-source AI models in safe formats
- Monitor and revoke nodes that misbehave
- Group-held k-of-n key recovery — no single member or outsider can unlock alone
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).
- Networking: libp2p, WireGuard, Headscale, open mesh overlays
- Orchestration: custom P2P scheduler, Ray, Docker (Engine), Podman
- Model runtime: ONNX Runtime, PyTorch, TensorFlow Lite, llama.cpp
- Storage: IPFS, syncthing, rsync-style sync, local disk caches
- Coordination: metadata registry, DHT, small bootstrap servers
- Models: Apache-2.0/MIT open weights only as defaults (e.g. Mistral, Qwen2.5, OLMo); restricted-license weights (e.g. Meta Llama) never bundled or redistributed
7. Practical Phases
1. Prototype
- Set up 2–3 trusted machines
- Share model inference tasks
- Use open models and local caching
2. Add discovery
- Implement peer discovery over the internet
- Handle NAT traversal
3. Expand
- Add more volunteer nodes
- Add distributed storage for models/data
- Add task scheduling and failover
4. Governance
- Add identity and reputation
- Define sharing policies
- Add credit / resource accounting
8. Reality Check
- This is not literally “zero cost”:
- hardware, electricity, and network usage still matter
- true “no cost” only exists if participants willingly donate resources
- It is possible to avoid commercial cloud fees by sharing existing machines and bandwidth
- The system will be slower and harder to manage than a centralized cloud, but it can still deliver many cloud-like AI services
9. Cloud Feature Replication
To make this the cheapest ever solution while still matching public cloud capabilities, the plan must replicate these cloud principles:
- Compute as a service
- dynamic task scheduling across nodes
- support for CPU, GPU, and accelerator workloads
- Object and model storage
- distributed caching and content-addressed storage
- tiered persistence: local disk, peer caches, archival nodes
- Networking and service gateway
- API gateway for user access
- encrypted P2P tunnels and mesh networking
- Automation and self-service
- command / API-driven provisioning
- node onboarding and resource discovery automation
- Monitoring and observability
- distributed metrics collection
- health checks, logging, and SLA-based routing
- Security and identity
- node identity and service authentication
- data encryption, sandboxing, and policy enforcement
- Resilience and failover
- redundant task execution
- automatic rerouting around unavailable nodes
10. Community Hardware Strategy
Community and low-cost hardware are the backbone of this plan. Key design choices:
- Treat every participant as a “community node” rather than a cloud instance
- Accept heterogeneity: different CPU types, GPUs, and memory sizes
- Use lightweight runtimes and model quantization to fit cheap hardware
- Cache models locally to reduce repeated downloads and network cost
- Implement reputation and credit so reliable nodes are preferred
- Align incentives with cooperative use, such as shared access, reputational rewards, or cost offsetting
- Add optional redundancy by assigning duplicate tasks to trusted nodes for best-in-class reliability
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:
- Lightweight roles first: mesh relay, blob cache, telemetry, small quantized-model inference
- Battery/network aware: contribute only while charging and on unmetered networks by default (user-controlled)
- Thermal & battery safety guard: pause or scale down on rising temperature or low battery; hard stop on thermal thresholds — a device must never overheat or feel like a virus gulping resources
- Same security model: enrolled certificate, mutual TLS, passkey portal, share declarations like any node
- Mobile portal: manage share limits, usage, and earned service from the phone after passkey sign-in (PWA, no app store needed to start)
- Delivery path: the Go agent cross-compiles to android/arm64 and ios/arm64; PWA and sideload first, store submissions later
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:
- Every node — mobile and standalone — starts at a safe **5%** default of CPU/IO/memory
- Fully **tunable up to a 70% ceiling**: a dedicated or idle machine can be set high; a personal phone or laptop stays low
- The cap never reaches 100% — 70% max leaves headroom so the device stays responsive, cool, and safe even when contributing hard
- Raising the cap is explicit, per-resource, and instantly reversible from the portal
- On mobile, a thermal/battery guard sits on top of the cap; the cap itself applies to all nodes
10.1 Resource Sharing Controls and Reciprocity
Members stay in control of what they give, and what they give determines what they get:
- Default cap is 5% (see 10.0.1); raising it is explicit and reversible
- Each node declares share limits: CPU cores/percent, IO bandwidth, disk quota, network bandwidth, and share hours (e.g. nights only)
- The agent enforces declared limits locally; the scheduler never exceeds a node's declaration
- Contribution is metered (the ledger) and reciprocated: members earn service capacity proportional to what their nodes contribute, with community-configurable floors so small contributors are never locked out
- Changing a share declaration is a one-click console action, effective immediately
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:
- Use: call AI and other services, manage API keys, see usage and cost saved
- Contribute: set share limits (starting at the 5% default), see contribution and earned service on the ledger, view the network map
- Same portal on desktop and mobile; everything a member can do lives in one authenticated place, backed by the same HTTP API the CLI uses
10.2 Community Node Tracking and the Network Map
Every node in the community mesh is tracked and visible:
- Nodes carry an optional hierarchical location label: continent / country / state / city / village
- The console renders a live network map: green dots for healthy nodes, red for down, grouped by location and expandable level by level
- The map is the community's shared operational picture — who is up, where capacity lives, where coverage is thin
10.3 Locality-Aware Redundancy
Failure tolerance is built around geography:
- Replicas are placed across localities: at least one copy in another city/region when the mesh spans them
- Requests prefer nearby nodes for latency; failover widens outward (village → city → state → country → continent)
- Local clusters keep serving their locality even when cut off from the wider mesh
11. Rule Engine Rules
The rule engine should enforce replication, monitoring, and failover for reliable services on community hardware.
- Replicate each compute task to multiple nodes when needed:
- primary/secondary pairs for critical work
- k-of-n redundancy for higher confidence
- Prefer nodes with higher reputation and recent success history
- Track node health with heartbeats, status updates, and health checks
- Mark nodes unhealthy after missed heartbeats or repeated failures
- Reroute failed or slow tasks automatically to alternate nodes
- Use local or nearby cached model copies to minimize network overhead
- Retry failed executions transparently and checkpoint long-running work
- Validate results before returning them for critical or non-idempotent tasks
- Use selective redundancy so high-priority jobs get stronger protection while low-priority jobs stay cheap
12. Example Outcome
A working “cloudless AI” system can provide:
- distributed AI inference
- collaborative model hosting
- decentralized data indexing
- edge-based AI services
- private compute on shared infrastructure
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
- Cloud services are costly for continuous or large-scale workloads.
- Proprietary clouds centralize data and compute control.
- Existing distributed systems lack integrated orchestration, replication, and trust for general compute and AI workloads.
1.2 Contribution
- Define a decentralized compute architecture that replicates cloud features on community hardware.
- Explain how AI becomes a key built-in service within this broader platform.
- Propose a rule engine for replication, monitoring, and failover.
- Describe a governing model for trust, reputation, and low-cost participation.
- Identify a practical path for prototype deployment on heterogeneous hardware.
2. Related Work
2.1 Public Cloud AI
- AWS, Azure, GCP AI services
- Centralized management, elasticity, service abstraction
2.2 Federated Learning and Distributed AI
- TensorFlow Federated
- OpenMined
- Flower
2.3 Decentralized Compute and Storage
- IPFS, Filecoin
- Golem, iExec, Akash
- Community networks and edge compute
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:
- Client / API Layer
- Federation Gateway
- Node Discovery and Task Orchestration
- Federated Node Mesh
- Distributed Model and Data Storage
- Security and Identity services
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
- Prioritize low-cost community compute over rented infrastructure.
- Keep sensitive data local and enforce privacy-first processing.
- Design for cooperative and community-native participation.
- Replicate only what matters to remain efficient.
- Optimize for heterogeneous, low-cost hardware.
- Reward reliable nodes through reputation and trust.
- Build resilience with decentralized redundancy and failover.
- Maintain open interoperability with standard model formats and APIs.
- Serve customers who value cost control, privacy, and decentralization.
5. Rule Engine
The rule engine enforces service behavior:
- Replicate critical tasks across multiple nodes.
- Prefer trusted nodes with strong success histories.
- Monitor node health via heartbeats and status checks.
- Mark unhealthy nodes and reroute tasks automatically.
- Use local caches and nearby replicas to minimize network overhead.
- Retry failed tasks transparently and checkpoint long-running work.
- Validate critical outputs before they are returned.
- Apply dynamic redundancy based on priority and cost.
6. Replication and Failover Strategy
6.1 Compute Replication
- Primary/secondary task assignment
- k-of-n redundancy for critical jobs
- Speculative execution on backup nodes
6.2 Data and Model Replication
- Distributed model storage via IPFS/DHT
- Local caching for frequently used artifacts
- Multiple replicas of popular models and shards
6.3 Failure Handling
- Automatic rerouting when nodes fail or become slow
- Transparent retries and checkpoint resume
- Quorum or majority validation for critical results
7. Community Hardware Strategy
The platform is designed for heterogeneous, inexpensive hardware. Key aspects include:
- Support for mixed CPU/GPU resources
- Lightweight runtimes and quantized model execution
- Local caching to reduce repeated downloads
- Incentive structures for node reliability
- Optional redundancy through task duplication
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:
- Prototype deployment on 2–5 community nodes
- Measure latency, throughput, and cost against cloud baselines
- Test replication and failover under node churn
- Evaluate privacy benefits for local data handling
- Analyze reliability when using low-cost hardware
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
- Build a reference implementation
- Develop reputation and incentive mechanisms
- Explore formal security and privacy guarantees
- Add support for broader AI model lifecycle management
- Evaluate real-world community deployments
References
- Placeholder for prior work citations on cloud computing, federated learning, decentralized storage, and distributed systems.
CloudLess · Apache-2.0 · published from the open repository.