vminfo

vminfo - cross-platform terminal system monitor, web dashboard, MCP server, and Go library

A single-binary system monitoring toolkit for Linux, macOS, and Windows. Inspect CPU, memory, disk, network, and load in a live terminal UI, export JSON for automation, open a browser dashboard, connect an MCP client, or embed host metrics in Go. No background agent or configuration is required for local monitoring.

Documentation: vminfo documentation · 中文说明 · MCP server · HTTP API reference · Docs source

Preview · Quick start · Why vminfo · Commands · MCP · Platform support · FAQ · Contributing

Preview

The demo cycles through the overview, Linux process view, and help. Screens may vary slightly by terminal width, font, and theme.

Web dashboard	Linux process view

Quick start

# 1. Install - one-line script (Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/cloudapp3/vminfo/main/install.sh | sudo bash -s -- --dir /usr/local/bin

# Or install without sudo to an auto-detected user directory
curl -fsSL https://raw.githubusercontent.com/cloudapp3/vminfo/main/install.sh | bash

# 2. Run - interactive TUI
vminfo

# 3. Or get a JSON snapshot for scripting
vminfo summary --json

That's it. No background agent, config file, or setup is required for local monitoring. The installer downloads the matching GitHub Release and verifies its SHA-256 checksum by default.

The install script auto-selects a directory when --dir is not set: /usr/local/bin → ~/.local/bin → ~/bin.

Other installation methods

Windows release builds are available for amd64. Extract vminfo.exe from the release ZIP and place it in a directory on your PATH.

Custom Linux/macOS install directory:

curl -fsSL https://raw.githubusercontent.com/cloudapp3/vminfo/main/install.sh | bash -s -- --dir /opt/bin

If you install to a custom directory such as /opt/bin, make sure that directory is in your PATH, or symlink the binary into /usr/local/bin:

sudo ln -sf /opt/bin/vminfo /usr/local/bin/vminfo

Why vminfo

vminfo is built for developers, SREs, DevOps engineers, and server operators who want fast, low-friction visibility into host metrics without installing a monitoring stack.

Use vminfo when you need to:

• monitor CPU, memory, disk, network, and load from a live terminal dashboard
• inspect and manage Linux processes without switching tools
• export stable JSON snapshots or JSON Lines for scripts, CI, and automation
• open a lightweight browser dashboard with vminfo --web
• let a local MCP client inspect host state and run bounded network diagnostics
• embed host metrics collection or the TUI into your own Go tools

The same binary provides five interfaces:

• Terminal UI - full-screen, live-updating overview and process views
• JSON and text CLI - one-shot or streaming output for automation
• Web dashboard - browser UI with REST and WebSocket endpoints
• MCP server - read-only stdio tools for local AI clients
• Go library - public collection APIs plus an embeddable TUI package

Collected metrics include CPU per core, memory, swap, disk, disk I/O, network, load, TCP/UDP counts, TCP state distribution, conntrack usage, interface rates, processes, temperatures, uptime, and host metadata.

If vminfo is useful on your machines, star the repository to help other operators discover it.

vminfo compared with other system monitors

These tools serve different operational needs. See the detailed comparison guide before choosing for production use.

Cross-platform monitoring features

• Host resources - CPU, memory, swap, disk, disk I/O, temperature, uptime, and metadata
• Network visibility - total throughput, per-interface rates, IP addresses, TCP/UDP counts, TCP states, and Linux conntrack usage
• Host health - resource score and focused warnings exposed in both the dashboard and /api/v1/health
• Network diagnostics - DNS, TCP port, TCP/ICMP ping, and public IP/ASN/geo lookup commands
• International UI - built-in English, Chinese, German, Spanish, French, Japanese, Korean, Portuguese, and Russian translations

Commands

vminfo                 # launch TUI
vminfo info            # TUI alias
vminfo summary         # one runtime snapshot (text)
vminfo summary --json  # one runtime snapshot (JSON)
vminfo watch           # stream snapshots continuously
vminfo watch --json    # stream JSON lines
vminfo watch --count 1 # single sample then exit
vminfo --web           # web dashboard on 127.0.0.1:20021
vminfo --web --token   # auto-generate a dashboard token
vminfo --web --token secret-token
vminfo --web --tui     # web + TUI together
vminfo --web --bind 0.0.0.0 --port 8080 --token
vminfo ps              # Linux-only process list
vminfo ps nginx        # filter by name, user, pid, or command
vminfo ps --filter ssh # explicit process filter for scripts
vminfo ps --tree       # render a process tree
vminfo ps --watch      # refresh process table continuously
vminfo ps --limit 20   # show the first 20 rows after sort/filter
vminfo ps --json       # processes as JSON
vminfo ps --sort mem   # sort by cpu|mem|pid|name
vminfo kill <pid>      # SIGTERM a process (Linux)
vminfo net dns vminfo.bestcheapvps.org            # resolve a domain (system or --server)
vminfo net port vminfo.bestcheapvps.org 443       # test TCP port connectivity / latency
vminfo net ping vminfo.bestcheapvps.org --tcp-port 443   # TCP ping (default; cross-platform)
vminfo net ping vminfo.bestcheapvps.org --mode icmp      # real ICMP ping (needs privileges)
vminfo net ip                         # your public IP + ASN / geo
vminfo net ip 8.8.8.8                 # lookup a specific IP
vminfo mcp             # read-only MCP server over stdio
vminfo update          # check + install the latest tagged release
vminfo update --check  # check without installing
vminfo update --version vX.Y.Z
vminfo --lang zh       # switch UI language

Built-in languages: en, zh, de, es, fr, ja, ko, pt, ru.

net subcommand flags may appear before or after the target, so both net ping --tcp-port 443 example.com and net ping example.com --tcp-port 443 are accepted. CLI ping count is limited to 1-100 and probe timeouts must be positive and no greater than 10 seconds.

MCP server

vminfo mcp starts a foreground, tools-only MCP server over stdio. It does not listen on a network port, run the web dashboard, or perform background update checks. The process exits when its MCP client disconnects.

Available tools:

Claude Desktop configuration:

{
  "mcpServers": {
    "vminfo": {
      "command": "/usr/local/bin/vminfo",
      "args": ["mcp"]
    }
  }
}

Codex configuration:

[mcp_servers.vminfo]
command = "/usr/local/bin/vminfo"
args = ["mcp"]

Example prompt after connecting an MCP client:

Check this host's CPU, memory, disk, and network health, then list the five processes using the most memory. Do not make any changes.

The MCP server is read-only: it does not expose kill, update, shell execution, file writes, prompts, or resources. Process command lines are hidden unless a call explicitly sets include_command to true; command arguments can contain credentials or other secrets. While command lines are hidden, the process filter does not search them. Snapshot and process results are sent to the model configured by the MCP client. Network tools contact the requested target, and lookup_ip makes an explicit outbound request to ip.bestcheapvps.org.

Platform support

TUI requires a real TTY. ps, kill, and the MCP list_processes tool are Linux-only by design.

Web dashboard

vminfo --web                      # default: 127.0.0.1:20021
vminfo --web --token             # auto-generate a token and print a ready-to-open URL
vminfo --web --token my-token    # use a fixed token
vminfo --web --bind 0.0.0.0 --port 8080 --interval 1s --token

Add --token when you want to protect the dashboard in a browser:

• --token some-value uses that exact token
• bare --token auto-generates a URL-safe token
• the first successful /?token=... visit sets a cookie, so later page/API/WebSocket requests can continue without keeping the token in the address bar

Loopback binds (127.0.0.1, ::1, or localhost) may run without a token. Any non-loopback bind, including 0.0.0.0, requires an explicit --token or bare --token request. An empty --bind= is rejected rather than interpreted as all interfaces.

The built-in server uses HTTP. A token controls access but does not encrypt the connection. For remote access, put vminfo behind an HTTPS reverse proxy or use an SSH tunnel; do not expose its HTTP port directly to an untrusted network.

When binding to all interfaces with the required token, startup output shows friendlier, ready-to-open URLs instead of only 0.0.0.0:

Web dashboard:
  Local  http://127.0.0.1:20021/?token=example-token
  Public http://203.0.113.10:20021/?token=example-token   # when a public IPv4 is present
  LAN    http://192.168.1.23:20021/?token=example-token   # fallback when only a LAN IPv4 is present

Token-protected printed URLs always include ?token=... so they can be opened directly.

Web mode keeps stdout quiet during normal browsing: routine HTTP request logs and WebSocket connect/disconnect logs are suppressed, while real startup and error messages are still shown.

The web server always enforces browser same-origin access:

• when a token is enabled, dashboard pages, JSON APIs, and /ws require the token or auth cookie
• permissive Access-Control-Allow-Origin: * is never exposed
• REST requests and WebSocket upgrades with an Origin header must match the dashboard host
• unauthenticated loopback mode only accepts localhost or loopback-IP Host headers, preventing DNS rebinding
• native clients without an Origin header remain supported

Endpoints:

• GET /api/v1/snapshot — current snapshot JSON
• GET /api/v1/processes — process list with optional filter / q, sort, and limit query parameters
• GET /api/v1/health — lightweight health score and resource warnings
• GET /ws — live WebSocket stream
• POST /api/v1/net/diag — run a same-origin network diagnostic ({"action":"dns|port|ping|ip","target":...}); ping count is limited to 10 and per-probe timeout to 3 seconds

The dashboard ships with switchable themes (Auto / Neon / Light / Terminal / Synthwave) from the header; "Auto" follows the OS color scheme. JetBrains Mono is embedded, so the dashboard stays self-contained and works offline with no external font requests.

Go library

Collect host metrics from your own Go program:

package main

import (
    "context"
    "fmt"
    "time"

    "github.com/cloudapp3/vminfo"
)

func main() {
    ctx := context.Background()

    static, _ := vminfo.CollectStatic(ctx)
    stats, _ := vminfo.CollectStats(ctx, vminfo.Options{SampleInterval: time.Second})

    fmt.Println(static.Hostname, stats.CPU)
}

Launch the same interactive terminal UI from another Go CLI:

package main

import (
    "context"
    "log"

    vminfotui "github.com/cloudapp3/vminfo/tui"
)

func main() {
    if err := vminfotui.Run(context.Background(), vminfotui.Options{Lang: "en"}); err != nil {
        log.Fatal(err)
    }
}

tui.Options also accepts custom Stdin and Stdout streams for embedded CLIs and tests.

Public packages: github.com/cloudapp3/vminfo · github.com/cloudapp3/vminfo/tui

Exported collection types: StaticInfo · RuntimeStats · ProcessInfo · Snapshot · AppMetadata

Self-update

Release builds can update themselves from GitHub Releases:

vminfo update
vminfo update --check
vminfo update --version vX.Y.Z

See the changelog for release-specific changes.

TUI controls

Status badges: LIVE · PAUSED · LOADING · ERROR · STALE

FAQ

Does vminfo require a daemon or configuration file?

No background service or configuration file is required for the TUI, summary, watch, or network diagnostics. Web mode starts a foreground HTTP server only when you request vminfo --web; MCP mode starts a foreground stdio server only when an MCP client runs vminfo mcp.

Does vminfo require root privileges?

Normal monitoring commands do not require root. Installing into a protected directory, sending signals to other users' processes, and ICMP ping may require elevated OS permissions.

Which features work on Windows and macOS?

The TUI, summary, watch, web dashboard, MCP server, and update checks are cross-platform. ps, kill, and the MCP process-list tool are Linux-only, and Windows self-update is currently check-only. See Platform support.

Can I use vminfo in scripts and CI?

Yes. Use vminfo summary --json for one snapshot or vminfo watch --json for a stream of JSON Lines.

How should I access the web dashboard remotely?

Keep the default loopback bind when possible. Non-loopback binds require a token, but the built-in server is HTTP only; use an HTTPS reverse proxy or SSH tunnel for remote access.

Is vminfo a replacement for htop or btop?

It overlaps with local resource and Linux process monitoring, but also targets JSON automation, browser access, and Go embedding. Choose based on the workflow summarized in the comparison.

How do I update vminfo?

Run vminfo update from a tagged Linux or macOS release build. Use vminfo update --check to inspect available versions without installing.

Community & Support

• Read the documentation or support guide
• Join the VMPulse Telegram group for usage questions and feedback
• Open a structured issue for a reproducible bug or feature request
• Follow SECURITY.md to report a vulnerability privately
• Browse GitHub Releases for binaries, packages, checksums, and release notes

Contributing

Contributions are welcome - bug reports, feature ideas, documentation improvements, tests, platform compatibility fixes, and pull requests.

If you want to help:

1. Open an issue to discuss a bug, feature, or non-trivial change
2. Read CONTRIBUTING.md
3. Fork the repository and make a focused change
4. Run go test ./..., go test -race ./..., and go vet ./...
5. Open a pull request

Questions before opening a PR? Join Telegram.

Build from source

git clone https://github.com/cloudapp3/vminfo.git
cd vminfo
go build -ldflags "\
  -X github.com/cloudapp3/vminfo.Version=vX.Y.Z \
  -X github.com/cloudapp3/vminfo.Commit=$(git rev-parse --short HEAD) \
  -X github.com/cloudapp3/vminfo.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ) \
  -X github.com/cloudapp3/vminfo.Channel=stable" \
  ./cmd/vminfo

Development

gofmt -w $(git ls-files '*.go')
go test ./...
go test -race ./...
go vet ./...
go run ./cmd/vminfo summary --json

Documentation

• Documentation website
• Chinese documentation
• HTTP API reference
• Changelog
• Feature benchmark and roadmap
• Documentation source repository
• CONTRIBUTING.md

License

MIT