vmbench

Cross-platform VPS benchmark toolkit written in Go, with a TUI interface.

vmbench measures CPU / memory / disk with external tools only (sysbench, fio, OpenSSL by default on Linux; more opt-in), diagnoses VPS network quality (route, ping, speed, IP quality, mail, media unlock), and exports JSON / HTML reports for comparison and automation. It reports raw metrics and structured diagnostics. On top of that raw layer, the optional vmbench score command derives a deterministic assessment (dimension indexes, scenario fit, coverage disclosure) from a versioned baseline — raw measurements always remain the source of truth.

Documentation: 中文说明 · Full capability reference · Tech stack · Changelog

Quick start · Install · Commands · Flags · VPS Checkup · TUI · Documentation

Quick Start

# One-line install (Linux / macOS; latest GitHub Release, SHA-256 verified),
# then put it on PATH for the current shell
VMBENCH_BIN_DIR="$(
  curl -fsSL https://raw.githubusercontent.com/cloudapp3/vmbench/main/install.sh | bash -s -- --print-install-dir
)" && export PATH="$VMBENCH_BIN_DIR:$PATH"

vmbench                          # interactive TUI (default)
vmbench --json report.json       # hardware benchmark via external tools (default selection)
vmbench --preset quick           # fast overview: hardware + network info + speed + IP quality
vmbench score report.json        # deterministic assessment (dimension indexes, profile fit, coverage)
vmbench update                   # self-update from GitHub Releases

Install

The one-liner above installs the latest release for your OS/arch and verifies its SHA-256 against checksums.txt. Without --dir, the install directory is picked automatically: an existing installation in ~/.local/bin, ~/bin, or /usr/local/bin is reused; a root install uses /usr/local/bin; an unprivileged user prefers ~/.local/bin or ~/bin when either is already on PATH. For an automatic home-directory install that is not yet on PATH, the installer adds an idempotent entry to the current shell's startup file (.zshrc, .bashrc, or .profile) and prints the exact reload command; other shells get a warning.

# System-wide install (uses sudo only for target checks and writes)
curl -fsSL https://raw.githubusercontent.com/cloudapp3/vmbench/main/install.sh | bash -s -- --system

# Go toolchain
go install github.com/cloudapp3/vmbench/cmd/vmbench@latest

Other installer flags: --version vX.Y.Z pins a release, --no-modify-path keeps shell startup files untouched, --print-install-dir prints the selected directory for scripts, and --skip-verify skips checksum verification. --dir PATH (mirrored by VMBENCH_INSTALL_DIR) selects a custom directory; explicit directories never modify shell startup files, so make sure the directory is on PATH. GITHUB_TOKEN/GH_TOKEN helps with API rate limits or private releases.

Uninstall

curl -fsSL https://raw.githubusercontent.com/cloudapp3/vmbench/main/install.sh | bash -s -- --uninstall

Removes the binary, the platform data directory (~/.local/share/vmbench on Linux, ~/Library/Application Support/vmbench on macOS) including all locally stored benchmark history, the TUI preferences directory (~/.config/vmbench on Linux; on macOS it lives inside the data directory), any manually created vmbench systemd/launchd unit, and the installer-owned # vmbench user install PATH entries from .zshrc/.bashrc/.profile. Hand-written PATH lines and reports under a custom VMBENCH_HISTORY_DIR are preserved. Use sudo bash -s -- --uninstall for a root-owned system installation.

The installed binary can also uninstall itself: vmbench uninstall prints the removal plan (history record count, fetched tools, TUI preferences, data directory, the binary itself), asks for confirmation on a terminal, and removes owned directories before the binary. It keeps the binary whenever a removal fails, so an interrupted uninstall can simply be rerun. Shell startup files and services are left to install.sh --uninstall, which delegates to this command when available and stops a manually created service and cleans its PATH entries afterwards. Flags: --dry-run previews the plan, --yes skips the prompt, --json emits a structured plan/result for scripts.

Windows: download vmbench-<version>-windows-<arch>.zip from Releases (WinSAT provides the default hardware probes).

Self-update

vmbench update                   # check and replace this binary in place
vmbench update --check           # report the latest release without installing
vmbench update --version v0.6.0  # pin / downgrade to a specific release
vmbench update --check --json    # machine-readable status for scripts

Downloads are SHA-256 verified against the release checksums.txt, then atomically renamed over the running executable. GITHUB_TOKEN/GH_TOKEN is honored for API rate limits; deb/rpm installs should prefer the package manager.

Commands

Command	Description
vmbench	Interactive TUI (no flags) — or run the benchmark when flags are present
vmbench [flags]	Run the benchmark: hardware only by default, checkup sections via preset / only / skip
vmbench nodes <command>	List / verify / update / health-check the versioned node catalog
vmbench mcp serve [--transport stdio]	Expose vmbench tools to LLM clients via MCP stdio
vmbench list	List available workloads
vmbench sysinfo [--json]	Show system information
vmbench score <report.json|->	Derive a deterministic assessment from a report against the versioned scoring baseline
vmbench history <command>	Add / list / show / delete local reports
vmbench update [--check] [--version TAG]	Self-update from GitHub Releases (SHA-256 verified)
vmbench version	Show version

Common Flags

Flag	Default	Description
--iterations	3	Iterations per hardware workload (1-9)
--filter	all	Regex to select workloads
--hardware-tool	platform default	sysbench, openssl, fio, dd, stream, mbw, geekbench, winsat, or all
--preset	—	Scenario preset: quick, website, proxy, mail
--only / --skip	—	Select or skip sections
--ip-version	v4	v4, v6, or dual
--speed-provider	cloudflare	cloudflare, speedtest_net, speedtest_cn, china_isp, speedtest_isp, iperf3
--ip-quality-source	builtin	builtin; opt-in securitycheck (external 18-database binary)
--redact	ips	Mask this machine's public IPv4/IPv6 in reports (none to keep real addresses)
--media-set	globe	globe covers the 41 international platforms (AI services included); all runs every platform, or combine region IDs
--node-catalog	embedded	embedded, auto (fetch each run, silent cache/embedded fallback), or a JSON path
--node-revision	—	Pin an exact catalog revision; fails before probes start on mismatch
--iperf-host	—	iperf3 server for the iperf3 speed provider
--json / --html / --markdown	—	Write JSON / HTML / forum-pasteable markdown report to file
--quiet	false	Suppress progress output
--auto-swap	false	(Linux) low-memory geekbench runs: create a temporary swapfile without asking, remove it afterwards
--save-history	false	Save the report to local history (--history-tag to label)
--lang	auto	en or zh-CN (also VMBENCH_LANG)

Without --preset / --only / --skip the run is hardware-only; network sections are opt-in via a preset or explicit selection. When the effective selection is exactly the hardware section the output is a benchmark (run-kind) report — identical to pre-v0.8.0 vmbench run — otherwise a composite checkup report. Full flag tables: vmbench --help or the capability reference.

Reports are redacted by default: this machine's public IPv4/IPv6 addresses are consistently replaced with documentation-range placeholders (203.0.113.x, 2001:db8::x) across every surface — console, JSON, HTML, markdown, history, TUI, and MCP — including BGP/CIDR prefixes and reverse DNSBL labels that embed the address. Internal IPs, hostnames, route hops, and remote node IPs are kept. --redact none opts out (the CLI prints a sharing warning); TUI and MCP always redact.

--markdown report.md exports a share-ready paste: one heading per section with textgrid-aligned tables inside fenced code blocks (CJK-safe in any renderer), the media section folded to per-region counts plus exception items, and a provenance line (version, UTC time, catalog revision). It derives from the same redacted report as JSON/HTML and embeds no scores.

VPS Checkup

The checkup keeps the YABS-style one-command experience with ECS-style modular sections:

Section	Purpose
hardware	CPU / memory / disk benchmark report
network_info	Virtualization, public IPs, ASN/provider, NAT evidence, BGP/RDAP ownership view
route	China carrier / CERNET / CSTNET route diagnostics with return-route line classification (163 / 9929 / 4837 / CN2 / CMIN2 / CMI)
ping	China carrier TCP latency / jitter / loss with connection state
speed	Cloudflare / speedtest download + upload; optional China carrier (三网) providers
ip_quality	IP reputation: ip-api.com, ipapi.is, DNSBL, mail ports; opt-in securityCheck
reachability	Website HTTPS and Telegram DC TCP reachability
mail	Sequential mail-port reachability (open / refused / timeout / error)
media	Streaming / AI platform unlock probes (200+ services via UnlockTests)

Presets: quick (hardware, network_info, speed, ip_quality) · website (+ route, ping, reachability, mail) · proxy (network focus + media) · mail.

vmbench --preset proxy --ip-version dual
vmbench --only ping,mail
vmbench --route-presets gz,bj,sh,cd,cernet,cstnet
vmbench --speed-provider china_isp
vmbench --media-set jp,kr
vmbench --only hardware --hardware-tool geekbench
vmbench --node-catalog auto --save-history --history-tag weekly

The checkup succeeds only when every enabled section ends status=ok; enabled empty / skipped / partial / error states all fail the run. Reports keep the resolved node catalog source/revision and selected node IDs.

TUI

Launch with vmbench (no arguments):

• Dashboard with benchmark / history / sysinfo entry points; mouse clicks and wheel scrolling everywhere. The System card shows the machine's public IPv4/IPv6 with ASN org (probed async at startup, silent when offline; System Info expands to country and ISP)
• Config: one page for the same normalized fields as CLI/MCP — preset pills lead with Hardware Only (the CLI default) plus Custom and the checkup presets; section toggles reveal tool, filter, speed, route, media, and IP-source cards on demand, with a live planned-duration summary, missing-tool preflight, and 1-9 section jumps
• Running: one progress page for both kinds — workload grid for hardware runs, section grid for checkup runs, cancel modal included
• Results: cards / grouped / flat views; d opens per-workload detail with metrics, samples, errors, and raw tool output
• History: browse reports saved with --save-history (time, kind, tag, ID); Enter reopens a run in Results or a checkup in the checkup page, Esc returns
• Themes: press t on Dashboard to cycle; the choice is saved locally

Keys: ? help · ↑↓ navigate · Enter select · Tab switch view · d detail · s save · Esc back · q or Ctrl+C quit. Every page scrolls with PgUp/PgDn, Home/End, and the mouse wheel; fits an 80x24 terminal.

Languages

CLI, TUI, and console/HTML report labels are localized in English and Simplified Chinese — select with --lang, VMBENCH_LANG, or the TUI config. JSON field names, status enums, section IDs, and workload names stay English in every locale.

Platform Support

Capability	Linux	macOS	Windows
CLI / TUI / JSON / HTML	✅	✅	✅
Default hardware tools	✅ sysbench / fio / openssl	⚠️ openssl (others via package manager)	⚠️ WinSAT
Checkup network diagnostics	✅	✅	⚠️ partial / environment-dependent
MCP stdio server	✅	✅	✅

Missing fio or sysbench on a Linux host can be fixed without touching system packages:

vmbench tools fetch fio sysbench   # pinned static builds, SHA-256 verified, ~/.cache/vmbench/binaries

Downloads come from the tools release assets of this repository and are verified against hashes compiled into vmbench; --url accepts a mirror.

Network sections depend on local routing, DNS, firewall, IPv6, and sandbox permissions; failures are recorded as structured errors instead of being hidden.

Documentation

Topic	Where
Full capability reference (中文): CLI flags, checkup, node catalog, MCP, report formats, Go API	docs/capabilities.md
中文快速说明	docs/README.zh-CN.md
MCP tools, client config, safety defaults	MCP 大模型接入
Node catalog trust model and commands	版本化 Node Catalog
Hardware tool matrix and discovery	硬件测评能力
Tech architecture / current state	docs/tech-stack.md · docs/current-state.md
Contributing / building from source	CONTRIBUTING.md
Changelog	docs/CHANGELOG.md
External docs site source	cloudapp3/vmdocs

Community & Support

• 🐛 Found a bug or want a feature? Open an issue
• 🤝 Want to contribute? Start with CONTRIBUTING.md
• 💬 Community chat: VMPulse Telegram

License

MIT