# Cloudiy

> Cloudiy is an open compute protocol. Any identity, human or AI agent, rents computation from a peer-to-peer network and pays in USDC on Solana against an on-chain proof that the chosen provider signed the result. No account, no API key.

Agents are first-class. You discover providers, get a price quote, lock USDC in an on-chain escrow, run a workload, verify the signed result, and release payment. Payment uses the x402 pattern (HTTP 402, pay, retry) and the whole flow is exposed over MCP. The machine-readable contract (endpoints, error codes, quote and receipt shapes) is at /.well-known/cloudiy.json and /.well-known/ai-plugin.json.

## Why it exists
Cloudiy sells Workloads, not GPUs, VMs or Docker. Every other cloud hands you a machine and makes renting, wiring and trusting it your problem; here you declare the workload — what you need done — and the network resolves the machine, the price and the proof. Against the usual alternatives: Kubernetes orchestrates machines you already own (Cloudiy removes the "you own it"); RunPod is a marketplace you sign up for and must trust (here it's a wallet, no signup, and payment releases only against on-chain signed proof); AWS Batch is lock-in and a bill (here it's USDC per job on an open protocol, provider swappable); Fly.io deploys your app on their infrastructure (here any identity is provider or consumer, AI agents included).

## Protocol & specification
Cloudiy is a specification first, a program second — this repo's Rust workspace is ONE reference implementation, not the spec itself. Rendered on the site at /docs.html#protocol.
- PROTOCOL.md (v0.2 draft): Part I, the design model (§§1–9: design axioms, nouns, resource accounting, workload lifecycle, scheduler, universal API, SDK contract, entitlements/storage, reference-implementation map), and Part II, the normative wire specification (§§10–17: HTTP transport / verb→endpoint map, message schemas, /info node descriptor, x402 payment quote, error taxonomy, frame & size limits, versioning, kernels & capabilities). A second team can build an interoperable node from §§10–17 alone and prove it by passing the conformance suite. https://github.com/w3-surfer/cloudiy/blob/main/PROTOCOL.md
- Protocol ≠ implementation: the map in §9 is candid — protocol domain / scheduler / runtime are v0.1, node daemon / wire / SDKs are shipping, settlement is interfaces-only by design, and entitlements + external storage are still planned (RFC-0004).
- RFCs (docs/rfcs/; RFC-0002 is unused): 0001 Vision & Philosophy · 0003 Discovery & client-side scheduling · 0004 Stateless providers, storage & entitlements · 0005 Scheduling · 0006 Trust-minimized settlement without stake · 0007 Pricing & matching · 0008 Replicated settlement (quorum) · 0009 Persistent volume v2 (client-encrypted snapshots) · 0010 Failure handling (invariant: funds are never locked past the escrow deadline).
- Conformance: a zero-dependency black-box suite validates ANY implementation against the spec — point it at a node and every check cites the clause it enforces. https://github.com/w3-surfer/cloudiy/tree/main/conformance

## Start here
- Docs: /docs.html
- CloudiyOS (browser client): /os.html
- Source and SDKs: https://github.com/w3-surfer/cloudiy
- MCP: run `cloudiy mcp`, or `claude mcp add cloudiy -- cloudiy mcp`
- Python SDK exposes `as_tool_schema()` so an LLM can call remote compute as a function.

## The agent loop
1. discover: list providers, directly by Node ID or through a directory node.
2. quote: ask a provider for a price. A 402 response carries the USDC quote (price, mint, payee, expiry).
3. estimate (dry-run): get cost and availability without spending. See the contract file; marked planned where not yet live.
4. pay: lock USDC in the escrow (create_job). The private key never leaves the wallet.
5. run: submit the workload with the escrow account. The provider verifies the escrow on-chain, executes in isolation, and returns an ed25519-signed result.
6. verify: check the signature against the provider Node ID. This is the proof of origin.
7. release: pay the provider minus the 4% protocol fee. refund returns the funds after the timeout.

## Agents: quickstarts and MCP setup
Rendered on the site at /docs.html#agents — runnable "an agent rents compute" quickstarts plus the MCP setup, mirroring the repo.
- Setup: `cargo install --git https://github.com/w3-surfer/cloudiy cloudiy`, then register the server in `.mcp.json` (per project) or `~/.claude.json` (Claude Code, all projects); the same JSON block goes in `claude_desktop_config.json` for Claude Desktop. Config: `{"mcpServers":{"cloudiy":{"command":"cloudiy","args":["mcp","--max-spend-usdc","1.0","--read-only"]}}}`.
- 8 MCP tools: cloudiy_list_providers, cloudiy_quote, cloudiy_run_job, cloudiy_launch, cloudiy_deploy (read-only) and cloudiy_pay_escrow, cloudiy_release_verified, cloudiy_refund (sign transactions; hidden under --read-only).
- Typical loop: list_providers -> quote -> pay_escrow -> run_job -> release_verified.
- SDK quickstarts (Python, JavaScript, Go; Rust is the typed P2P crate): discover -> tool schema -> pay on 402 -> verify signature. All SDKs verify the ed25519 result signature by default and raise instead of returning unverified output (SignatureError in Python/JS/Go, SubmitError::BadSignature in Rust). Payment surfaces as PaymentRequired / PaymentRequiredError / *cloudiy.PaymentRequiredError.
- Caveat: the HTTP SDKs talk to one node you already know. Cross-network discovery is the CLI (`cloudiy providers --via <directory>`) or the cloudiy_list_providers MCP tool, over the P2P transport.

## Replicated settlement (quorum)
`cloudiy run --replicas N --pay --release` runs the same deterministic kernel on N independent providers and accepts the output only when a strict majority returns byte-identical signed bytes. One escrow per replica, funded up front and pinned to that provider; release_verified pays only the agreeing providers, and only after the chain re-checks the signature binding output to input.
Honest limit: quorum protects the answer, not a divergent replica's stake — release_verified is permissionless, so a malicious replica can self-settle its own escrow and keep that replica's price. The loss is bounded to one replica and payouts stay pinned to the provider you chose; the deterrent is the reputation hit. See docs/rfcs/RFC-0008-replicated-settlement.md.

## Guardrails for agents
- Spend caps: cap total and per-request USDC. The client refuses to exceed it. Over MCP the defaults are --max-spend-usdc 1.0 per session and --max-per-job-usdc 0.25, enforced server-side (exceeding either returns an error instead of signing); pay_escrow reports session_spent_usdc and session_cap_usdc on every call.
- Read-only mode: discover, quote and estimate with no ability to pay. Under --read-only the signing tools are not exposed to the model at all.
- Network guard: --rpc-url defaults to devnet and the mainnet check fails closed — it inspects the RPC host (not a substring), so an unrecognized RPC needs an explicit --allow-mainnet.
- Idempotency: pin an idempotency key or a job id so a retry after a timeout never pays twice.
- Signed receipts: every result yields a canonical receipt {job_id, output_hash, node_id, signature, cost_usdc}.
- Reputation and healthscore are queryable fields on a provider, so an agent can rank nodes before paying.

## Stable JSON contract
Errors and quotes are stable JSON with machine-readable codes, so an agent can decide on its own to pay, switch node, or abort. The full schema (error codes, quote shape, receipt shape, dry-run) lives in /.well-known/cloudiy.json.

## Networks
Escrow is live on Solana devnet (program 9zMBC7JDA8SJ2mk3ATYqRuJvn14MQyZVg9q3XPnzc1TN, 4% fee). Mainnet is planned. Treat devnet balances as test funds. The USDC mint is provider-specific and always arrives in the quote, never assumed.