vibedonate

BitTorrent-style mesh for AI inference — donate spare local compute across Claude, Codex, Gemini, Grok, pi. Your hardware, opt-in, metered.

Part of the Vibe Suite — companion tools for agentic coding CLIs (Claude Code, Codex, Gemini, Grok/pi, Kimi). Ships as CLI + npm package + MCP server.

Local-first: runs on your own machine, no data out (consent model in @pooriaarab/vibe-core).

v0 = the local-compute tier only. This release donates spare compute from a model on your machine, metered against a daily token cap and scoped to an allow-list. Routing a stranger's inference through your logged-in subscription or API key is a different trust surface and needs trust/legal design first (see docs/spec.md §"Open questions"). It is deliberately not in v0.

Install

# use it
npx vibedonate share --compute --idle 22:00-07:00 --cap 2M --pool allowlist:alice,bob

# or install globally
npm install -g vibedonate
vibedonate status

As a library:

npm install vibedonate

Quick start (CLI)

# Arm donation: local compute, 22:00–07:00 UTC, 2M tokens/day, only alice & bob.
vibedonate share --compute --idle 22:00-07:00 --cap 2000000 --pool allowlist:alice,bob

vibedonate — enabled · ● your machine · opt-in
  tier:     compute
  idle:     22:00-07:00 (UTC)
  cap:      2,000,000 tokens/day
  pool:     allowlist [alice, bob]
  usage:    donated 0 (today 0) · received 0 · 0 receipt(s)
  sharing:  yes (now 2026-07-26T03:17:55Z)

vibedonate status      # config + metering totals + whether sharing right now
vibedonate stop        # disable (revokes the donate:compute consent grant)
vibedonate mcp         # run the MCP server over stdio
vibedonate --version
vibedonate --help

State lives in $VIBEDONATE_DIR (default ~/.vibedonate): config.json, consent.json, metering.json. Nothing leaves your machine.

--pool

Value	Who can receive
open	any peer (you opted into the open pool)
org:acme or org:acme,alice,bob	a named group; trailing ids are its member allow-list
allowlist:alice,bob	an explicit peer-id list

--cap

A bare integer (2000000) or shorthand (2M, 500k). Scoped to the UTC day of each receipt.

Quick start (library)

import {
  createDonationConfig,
  isSharingActive,
  createMeteringLedger,
  authorizePeer,
  DONATE_COMPUTE_SCOPE,
  resolveCompute,        // cascade-backed on-device model resolution
  evaluateCapacity,      // the shared gate (MCP + mesh runtime)
  createLocalMeshRuntime,// serves a request + commits a receipt
  createDonationHooks,   // lifecycle events into the suite notify channel
  createConsentLedger, // from @pooriaarab/vibe-core, re-exported
} from 'vibedonate';

const config = createDonationConfig({
  idle: '22:00-07:00',      // wraps midnight
  cap: '2M',                // 2,000,000 tokens/day
  pool: 'allowlist:alice,bob',
});

const now = new Date();
const ledger = createMeteringLedger();       // in-memory; pass a store to persist
const consent = createConsentLedger();
consent.grant(DONATE_COMPUTE_SCOPE);          // arm donation

// The schedule boolean: enabled AND not busy AND under cap AND inside the window.
const active = isSharingActive(config, now, /* systemBusy */ false, ledger.totals(now).donatedToday);

// What "donate local compute" actually means: is there an on-device model to
// serve with? Resolved through vibe-core's cascade with egress forbidden, so it
// provably never leaves your machine (Ollama by default).
const compute = await resolveCompute();

// The shared gate both the MCP pre-flight and the mesh runtime consult.
// Adds consent, peer auth, and on-device availability to the schedule check.
const verdict = evaluateCapacity(config, consent, 'alice', 500, {
  now,
  systemBusy: false,
  donatedToday: ledger.totals(now).donatedToday,
  localAvailable: compute.available,
}); // { decision: 'allow' | 'deny', reason }

// The runtime: on allow it commits a real, hash-chained receipt. The P2P
// transport that feeds it remote requests is the one seam still to land.
const mesh = createLocalMeshRuntime({
  config: () => config,
  consent: () => consent,
  ledger: () => ledger,
  now: () => new Date(),
  systemBusy: () => false,
  resolveLocal: () => resolveCompute(),
});
await mesh.serve({ peer: 'alice', tokens: 500 });

Every function is pure and injectable: now, systemBusy, the metering store, and the consent ledger are all passed in — which is what makes the gating logic unit-testable to exhaustion.

MCP server

vibedonate mcp runs an stdio MCP server with two tools:

Tool	Args	Returns
status	—	config, metering totals, and whether the node is sharing now
request_capacity	{ peer, tokens }	allow/deny + reason

request_capacity is a pre-flight — it checks the donate:compute consent grant, peer authorization, on-device compute availability (resolved through vibe-core's cascade, egress forbidden), the idle window, local activity, and the daily cap, then answers. It does not consume capacity (recording real usage is the runtime half of the mesh, landing after v0). An agent running low on quota can ask the mesh for capacity behind your consent.

How it gates

Two functions, one truth:

• isSharingActive(config, now, systemBusy, donatedToday) — the schedule boolean. true iff the donation is enabled, the machine is not busy, today's donated tokens are under cap, and now is inside the idle window. Use this for "are we in a sharing state right now?" (status, dashboards).
• evaluateCapacity(config, consent, peer, tokens, ctx) — the full request gate, shared by request_capacity (MCP, no commit) and createLocalMeshRuntime().serve() (runtime, commits a receipt). Checks in order: enabled → consent grant → peer authorization → on-device compute available → not busy → idle window → daily cap → request fits remaining. One definition, consulted everywhere.

The on-device compute check is real: resolveCompute() runs the request through vibe-core's model-preference cascade with allowEgress:false, so only the on-device (local) tier is ever eligible — donated compute provably never leaves your machine. vibedonate ships an Ollama-backed chat runner (set VIBEDONATE_OLLAMA_MODEL); other runners drop into defaultChatRunners() as they land.

Metering receipts form a sha-256 hash-chain (seq → prev → hash); ledger.verify() detects any mutation, drop, or reorder — a local tamper-evident ledger, as the spec calls for. createLocalMeshRuntime().serve() is what actually appends to it, so the ledger is exercised (not write-only).

The one seam still to land

The P2P transport — carrying a remote peer's request to this node and the donor's inference back (encrypted peer-to-peer payload, relay only for discovery/NAT). MeshRuntime defines that seam; createLocalMeshRuntime implements everything except the transport, so a real request can be served and metered locally today, and the network layer plugs in later. See docs/spec.md §"Routing" / §"Open questions".

Suite events

share / stop / serve / deny publish normalized VibeEvents to the local notify channel (~/.vibe/notify.jsonl) via vibe-core's hooks bus, and a session-end milestone from any harness cleanly stops donation — so vibedonate is a first-class participant in the suite, not an island.

Prototype

Interactive, self-contained UX prototype (no build, no network): open docs/prototype.html in a browser.

Status

Prototype + spec + v0 implementation (local-compute tier). v0.2 makes "donate local compute" real: an on-device model is resolved through vibe-core's cascade (egress forbidden), the shared capacity gate is factored into one function, the mesh runtime actually commits hash-chained receipts, and donation lifecycle publishes to the suite notify channel. Account/credit-routing tiers need trust/legal design, and the P2P transport is the one seam still to land — see docs/spec.md.