Reference

IdleBench Docs

IdleBench is a CLI + verification API for IDLE compute providers. Run the CLI on your hardware to generate a signed benchmark report. It uploads to IdleBench and creates a public verification page with an embeddable badge.

Install CLI

Prerequisite: Node.js 18+

IdleBench runs via npx, which is bundled with Node.js. You must have Node.js 18 or higher installed on your machine before running any command.

Check your current version:

$node --version

If Node.js is not installed or below v18, download it from nodejs.org ↗ (LTS version recommended). Most Linux servers and macOS systems can install it via a package manager.

Run with npx (recommended)

Once Node.js is installed, run the benchmark using npx. This downloads and executes the CLI on-demand — no global installation needed.

$npx idlebench run

Install globally (optional)

If you benchmark frequently, install the CLI globally so it is always available without downloading each time:

$npm install -g idlebench
$idlebench run
npmjs.com/package/idlebench ↗

IdleBench never asks for private keys or seed phrases. A security notice is printed at every startup.

Run benchmark

The run command is the main benchmark flow. It walks you through an interactive setup, checks your hardware locally, calculates a score, saves a report file, and uploads it to IdleBench.

$npx idlebench run

Interactive prompts

Solana walletYour public wallet address (32–44 characters). Never your private key or seed phrase.
Resource nameA human-readable name for this compute resource, e.g. "RTX 4090 Training Node".
Resource typeGPU, CPU, API, Agent, PC, or Other.
IDLE endpoint URLOptional. Your IDLE Protocol gateway URL (from earnidle.com). Links the score to your listing. Press Enter to skip.

What gets checked

System infoOS, architecture, CPU model, CPU core count, total RAM.
GPU detectionGPU name, VRAM, vendor — detected via nvidia-smi first, falls back to systeminformation.
CUDACUDA availability and version, parsed from nvidia-smi output.
NVIDIA driverDriver version from nvidia-smi.
DockerInstalled version and daemon status via docker --version and docker info.
Docker GPU runtimeRuns docker run --rm --gpus all nvidia/cuda:12.3... to verify GPU passthrough.
Network latencyRound-trip latency to IdleBench API, measured 3 times and averaged.
CPU benchmarkLightweight SHA-256 hash workload (2048 iterations) and 128×128 matrix multiplication.

After the benchmark

A signed JSON report is saved locally as idlebench-report-[timestamp].json. It is uploaded to IdleBench automatically. The CLI prints your public verification URL and badge URL on completion.

If the upload fails (network error, server down), the local file is preserved. You can upload it later with idlebench upload.

Doctor

Checks your local environment without running a benchmark or uploading anything. Useful for diagnosing issues before committing to a full run.

$npx idlebench doctor
Node.jsVersion check — 18+ required.
OS & CPUOperating system, architecture, CPU model and cores.
RAMTotal system memory.
GPUGPU model, VRAM — same detection as the run command.
CUDACUDA availability and version.
NVIDIA driverDriver version if detected.
DockerDocker version and daemon status.
Docker GPUGPU passthrough test result.
NetworkLatency to IdleBench API — confirms internet connectivity.

Upload report

Uploads a previously saved report JSON without re-running the benchmark. Useful if a previous run completed locally but the upload step failed.

$idlebench upload ./idlebench-report-1717200000000.json

The report is validated against the expected schema before uploading. The report hash is verified to ensure the file has not been modified.

Version

Prints the installed CLI version.

$idlebench version

The CLI version is also embedded in every uploaded report under metadata.cliVersion.

Badge embed

Every verified resource gets a dynamically generated SVG badge. Embed it in GitHub READMEs, IDLE listings, or any website. The badge updates automatically when a new benchmark is run.

Badge URL

$https://idlebench.dev/api/badge/[resource-id]

Find the resource ID in the verification page URL: /resource/[id]

Markdown

$[![IdleBench](https://idlebench.dev/api/badge/RESOURCE_ID)](https://idlebench.dev/resource/RESOURCE_ID)

HTML

$<a href="https://idlebench.dev/resource/RESOURCE_ID"> <img src="https://idlebench.dev/api/badge/RESOURCE_ID" alt="IdleBench Verified" /> </a>

IDLE gateway

During idlebench run, you are prompted for your IDLE endpoint URL. Providing it links your IdleBench score directly to your IDLE listing — buyers see the grade before routing workloads to your resource.

IDLE endpoint URLs follow this format:

$https://gateway.earnidle.com/ep/[your-endpoint-id]

You can find your endpoint URL on your resource listing at earnidle.com. If you skip this field during the benchmark, you can re-run to add it at any time.

API reference

All endpoints are on the IdleBench base URL. Use the API Playground to test them live in your browser.

POST/api/reports/upload

Upload a benchmark report from the CLI. Creates provider and resource records if they do not exist. Invalidates cache. Returns the public resource URL, score, and grade.

POST/api/resources/create

Register a resource without a benchmark report. Pass walletAddress, name, resourceType, and optional idleGatewayUrl.

GET/api/reports/[id]/json

Download the raw benchmark report JSON for a given report ID. Returns the full signed report as a JSON attachment.

GET/api/badge/[id]

Returns an SVG badge for a given resource ID. Embeddable in README files, IDLE listings, and websites. Cached for 5 minutes.

GET/api/dashboard?wallet=[address]

Returns provider profile, resources, recent reports, and aggregate stats for a given Solana wallet address.

GET/api/health/check

Returns database connection status, API version, and resource/report counts. Use for uptime monitoring.

Scoring model

The final score is a weighted average of five sub-scores. The identical formula runs inside the CLI and on the server — you can verify any score independently.

GPU Capability30%

GPU model matched against a curated score table. VRAM adds a small bonus. CPU cores and RAM used as fallback for CPU-only nodes.

Docker & CUDA20%

Docker installed = +40 pts. CUDA available = +25 pts. Docker GPU runtime = +15 pts. Starts at 20.

Benchmark Performance20%

CPU hash workload timing, matrix calculation, and GPU container readiness. Faster = higher score.

Network Latency15%

Latency to IdleBench API. <20ms → 100. <100ms → 82. <200ms → 60. >600ms → 15.

System Stability15%

Starts at 75. Bonuses for ≥8 CPU cores, ≥16 GB RAM, ≥32 GB RAM, and ≥64 GB RAM.

Grade thresholds

Elite95 – 100
Verified A85 – 94
Verified B70 – 84
Risky55 – 69
Not RecommendedBelow 55

GPU score table (selected)

NVIDIA H100100
NVIDIA A10099
NVIDIA RTX 409097
NVIDIA RTX 408092
NVIDIA RTX 309088
NVIDIA V10082
NVIDIA RTX 308080
NVIDIA Tesla T468
AMD / Other GPU50–52
CPU-only (no GPU)Derived from CPU cores + RAM

GPU is matched by name substring. Unrecognised GPUs score 50.