Computeledger

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

npm install -g computeledger-cli

pip install computeledger-cli

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

$ computeledger keys generate --local

Generated Ed25519 keypair. Public key: COxK/lkoWxWB42QKXjvcHnmBPozH4Oo2JHoOKDjsoU8= Private key: ./.computeledger/keys/ed25519.pem (mode 600)

$ computeledger record --local --provider aws --hardware nvidia-h100 \ --duration-seconds 3600 --gpu-hours 1 --workload-type training Recorded usage receipt 39952199-0897-48b8-92c5-e351f773c83d.

$ computeledger ledger verify --local Ledger valid: 1 entries, unbroken hash chain.

Or wrap a real job directly, no manual record call needed:

computeledger run --local --provider on-prem --hardware nvidia-a100 -- python train.py

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:

computeledger verify receipt.json

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 verify detects, 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 computeledger binary verifies correctly against the PyPI package's computeledger binary. 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 --json for structured output, and computeledger mcp starts a Model Context Protocol server exposing record_usage, verify_receipt, list_ledger, and verify_ledger as callable tools.
• No shell-injection surface. computeledger run -- executes the wrapped command via an argument array, never a shell string, so metacharacters in the wrapped command are inert.

CLI reference

computeledger keys generate [--local]

computeledger keys show [--local] [--json] computeledger run [--local] [--provider ] [--hardware ] [--workload-type training|inference|unknown] [--no-record-command] [--json] -- computeledger record --provider --hardware --duration-seconds [--gpu-hours ] [--flops ] [--workload-type ] [--local] [--json] computeledger verify [--json] computeledger ledger list [--local] [--json] computeledger ledger show [--local] [--json] computeledger ledger verify [--local] [--json] computeledger export --format json|csv [--out ] [--local] computeledger mcp

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.

pip install computeledger-cli

Add it to your MCP client's config (for Claude Desktop, claude_desktop_config.json):

{

"mcpServers": { "computeledger": { "command": "uvx", "args": ["--from", "computeledger-cli", "computeledger", "mcp"] } } }

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:

record_usage(provider="lambda-labs", hardware="nvidia-h100", durationSeconds=3600, gpuHours=1, workloadType="training")

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

import { createReceipt, verifyReceipt, Ledger, verifyChain, loadKeyPair, resolvePaths } from "computeledger-cli";

from computeledger import create_receipt, verify_receipt, Ledger, verify_chain, load_key_pair

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.

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 omit