Computeledger README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Computeledger listing page.
ComputeLedger
Install • Quickstart • Features • CLI reference • Comparison • FAQ
Sign, hash-chain, and independently verify compute usage, portable across any provider.
ComputeLedger records a compute job's usage (GPU-hours, hardware, duration, workload type) as a cryptographically signed receipt and appends it to a tamper-evident local ledger. Anyone can verify a receipt's authenticity and the ledger's integrity without trusting the issuer, and without buying into any single cloud, chain, or vendor's stack.
Install
Both packages install the same computeledger command. Receipts are interoperable either way: a receipt signed by the npm binary verifies correctly with the PyPI binary, and vice versa.
Quickstart
Or wrap a real job directly, no manual record call needed:
run executes the wrapped command as a real subprocess (never through a shell), measures wall-clock duration, samples GPU utilization via nvidia-smi when one is present, and signs + appends the resulting receipt automatically. On a machine with no NVIDIA GPU, it still produces a duration-only receipt.
Give the receipt to anyone, on any machine, with no ComputeLedger account and no network call:
Why this exists
Multi-cloud and multi-provider GPU usage has no portable, verifiable record. A cost dashboard tells you what a provider says you used; it does not let a third party independently confirm that record wasn't altered after the fact, and it only works with the providers it integrates with. ComputeLedger is a lightweight, provider-agnostic attestation format: any process that can run a CLI command or call an MCP tool can produce a receipt, and any process, in any language, can verify one.
This is deliberately narrow. It does not compete with GPU marketplaces, cost dashboards, or confidential-computing platforms, all of which do real, different jobs. See the comparison below for exactly where the line is.
Features
- Ed25519 signatures via Node's and Python's built-in/standard crypto libraries. No bespoke cryptography, no external crypto dependency on the TypeScript side.
- Hash-chained ledger. Every receipt embeds the previous receipt's hash. Deleting, reordering, or editing a historical entry breaks the chain in a way
ledger verifydetects, even if the tampered entry's own signature still looks locally valid. - Cross-language interoperability by construction. A receipt signed by the npm package's
computeledgerbinary verifies correctly against the PyPI package'scomputeledgerbinary. Both implementations serialize the receipt payload through the same deterministic canonical-JSON algorithm before hashing. - Provider-agnostic. No account, no API key, no dependency on any specific cloud or chain. Works identically on a laptop, an on-prem cluster, or any cloud VM.
- Agent-native. Every subcommand supports
--jsonfor structured output, andcomputeledger mcpstarts a Model Context Protocol server exposingrecord_usage,verify_receipt,list_ledger, andverify_ledgeras callable tools. - No shell-injection surface.
computeledger run -- <command>executes the wrapped command via an argument array, never a shell string, so metacharacters in the wrapped command are inert.
CLI reference
| Flag | Meaning |
|---|---|
--local | Use ./.computeledger in the current directory instead of ~/.computeledger |
--json | Structured JSON on stdout instead of human-readable text |
--no-record-command | Omit the wrapped command string from the receipt (run only) |
MCP Server
ComputeLedger ships a Model Context Protocol server so an AI agent (Claude, Cursor, or any MCP-compatible client) can record and verify compute usage receipts directly, without a human invoking the CLI by hand. The Python package exposes the server as a subcommand rather than a separate console script, so computeledger mcp is the real invocation, not computeledger-mcp.
Add it to your MCP client's config (for Claude Desktop, claude_desktop_config.json):
The server exposes four tools, matching the CLI one-for-one:
record_usage(provider, hardware, durationSeconds, gpuHours?, estimatedFlops?, workloadType?, local?): signs a usage entry with the local Ed25519 key, appends it to the hash-chained ledger, and returns the signed receipt.verify_receipt(receipt): independently verifies a receipt's signature and hash integrity.list_ledger(local?): lists every receipt recorded in the local ledger.verify_ledger(local?): verifies every entry's signature plus the unbroken hash chain across the whole ledger.
Example call:
Transport is stdio, so there is nothing to host: the MCP client spawns the server as a local subprocess. Source: python/src/computeledger/mcp/server.py.
The npm package exposes the same four tools through the native TypeScript server (src/mcp/server.ts), invoked the same way with npx computeledger-cli mcp. Both implementations are cross-verified interoperable, and every tool returns the same structured JSON shape the CLI's --json mode produces.
Library API
Comparison
ComputeLedger occupies a narrow, specific gap: a portable, cryptographically verifiable usage receipt that doesn't require adopting any single provider's chain or platform. It is not trying to replace the tools below, each of which does a real, different job.
| ComputeLedger | SkyPilot | OpenCost | AICert | |
|---|---|---|---|---|
| What it is | Signed, portable usage receipts | Multi-cloud job orchestration + cost | Kubernetes/cloud cost monitoring | Training-provenance attestation |
| Cryptographic verification | Yes (Ed25519, offline) | No | No | Yes (TPM-based) |
| Provider lock-in | None | Orchestrates specific clouds | Kubernetes/cloud-native | None |
| Tamper-evident history | Yes (hash-chained ledger) | No | No | No (single artifact, no chain) |
| GitHub stars | New | 10,441 | 6,659 (CNCF) | 20 |
| Project activity | Active | Active | Active | No commits since June 2024 |
Agent-native (MCP/--json) | Yes | Partial (API/SDK) | No | No |
SkyPilot and OpenCost solve real, adjacent problems (running jobs across clouds, and visualizing what they cost) at far larger scale and maturity than this project. Neither produces a signed, independently verifiable usage record. AICert attempted training-compute provenance as a standalone OSS tool using TPM-bound attestation and has had no commits since June 2024; ComputeLedger's scope is deliberately narrower (a usage receipt, not a full training-provenance framework) and ships both an npm and a PyPI package from day one specifically so the receipt format isn't locked to one language's ecosystem.
What is ComputeLedger, and why does it exist
ComputeLedger is an open-source CLI, library, and MCP server for producing and verifying cryptographically signed records of compute usage. It exists because compute usage claims (GPU-hours consumed, hardware used, workload duration) currently have no portable, offline-verifiable proof format: a billing dashboard is only as trustworthy as the provider issuing it, and it only covers that one provider. ComputeLedger's receipts are self-contained, signed JSON objects that any party, on any machine, in either of two independently maintained language implementations, can verify without a network call or a trusted third party.
FAQ
Does ComputeLedger require an account or API key?
No. Everything runs locally. Keys are generated and stored on your own machine (~/.computeledger or ./.computeledger with --local).
Can a receipt be forged?
Not without the private key used to sign it. verify recomputes the payload hash and checks the Ed25519 signature against the embedded public key; the public key itself is part of the signed payload, so substituting a different key changes the hash and invalidates the receipt.
What happens if there's no GPU?
computeledger run degrades gracefully: it records wall-clock duration and whatever --hardware/--provider you specify, and simply omits GPU utilization samples if nvidia-smi isn't found.
Does this compete with SkyPilot or OpenCost? No, see the comparison table above. Those tools solve orchestration and cost visibility; ComputeLedger solves independent verifiability of a usage claim. The two are complementary: run SkyPilot or OpenCost for orchestration and cost, and drop ComputeLedger in wherever you need a signed record.
Is the receipt format a blockchain? It's a local, hash-chained, append-only log, similar in spirit to a Merkle log or a git commit chain. There's no token, no consensus mechanism, and no network involved.
Does ComputeLedger work on Windows? The npm and PyPI packages install and run on any platform Node.js 18+ or Python 3.10+ supports, including Windows. One caveat: private key files are written with POSIX permission bits (mode 600), which restrict access on Linux and macOS; Windows does not enforce the same POSIX permission model, so the file is written but the access restriction has no equivalent effect there. CI currently runs on Linux only, so Windows and macOS are not continuously tested upstream.
Can I use ComputeLedger for commercial projects? Yes. Both the TypeScript and Python packages are licensed Apache-2.0, which permits commercial use, modification, and redistribution, including in closed-source products, as long as the license and copyright notice are preserved.
What if I need multi-cloud orchestration or a cost dashboard instead? ComputeLedger doesn't do either. It only produces and verifies signed usage receipts. Pair it with SkyPilot for orchestration or OpenCost for cost visibility if you need those.
Contributing
Issues and pull requests are welcome. Run npm test (TypeScript) or pytest (python/) before opening a PR: both language implementations ship a full test suite, and any change touching the receipt or canonical-JSON format must keep both sides interoperable (see CONTRIBUTING.md).