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 -- <command> 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 <name>] [--hardware <type>] [--workload-type training|inference|unknown] [--no-record-command] [--json] -- <command...>
computeledger record --provider <name> --hardware <type> --duration-seconds <n> [--gpu-hours <n>] [--flops <n>] [--workload-type <type>] [--local] [--json]
computeledger verify <receipt.json> [--json]
computeledger ledger list [--local] [--json]
computeledger ledger show <id> [--local] [--json]
computeledger ledger verify [--local] [--json]
computeledger export --format json|csv [--out <file>] [--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.

Read the full README on GitHub →