vminfo

README

vminfo

One command to see everything running on your machine — CPU, memory, disk, network, processes — in a polished terminal UI, JSON, or browser dashboard.

中文说明：docs/README.zh-CN.md

Demo

Screens may vary slightly by terminal width, font, and theme.

TUI overview	Web dashboard

Processes	Help

Quick start

# 1. Install
go install github.com/cloudapp3/vminfo/cmd/vminfo@latest

# 2. Run — interactive TUI
vminfo

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

That's it. No config files, no daemons, no setup.

Install from GitHub Release

One-line install (Linux/macOS)

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

By default, the script installs vminfo into ~/.local/bin.

Install a specific version

curl -fsSL https://raw.githubusercontent.com/cloudapp3/vminfo/main/install.sh | bash -s -- --version v0.1.0

Install to a custom directory

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

What it does

vminfo gives you instant visibility into any host:

• TUI — full-screen, live-updating terminal dashboard with overview and process views
• JSON — machine-readable output for scripts, CI, monitoring pipelines
• Web dashboard — browser-based UI with REST and WebSocket endpoints (vminfo --web)
• Go library — import github.com/cloudapp3/vminfo and embed collection in your own tools

Collected metrics: CPU (per-core), memory, swap, disk, disk I/O, network, load, TCP/UDP counts, network interface totals/errors/drops, process list, temperatures, uptime, and host metadata.

Network & Load panel

• Load-aware coloring — 1m / 5m / 15m load values are colored by load / CPU cores, with mini bars in wide layouts
• Traffic split — total throughput is separated from the per-interface table for faster scanning
• Interface prioritization — active interfaces and warning interfaces sort before idle bridges / veth devices
• Noise reduction — idle interfaces fold on narrow layouts, while public/private IPs and errors/drops stay visually distinct
• Web parity — the web dashboard mirrors the same network semantics: totals, sorting, IP styling, and interface warnings

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 --tui     # web + TUI together
vminfo --web --bind 0.0.0.0 --port 8080
vminfo ps              # Linux-only process list
vminfo ps --json       # processes as JSON
vminfo ps --sort mem   # sort by cpu|mem|pid|name
vminfo kill <pid>      # SIGTERM a process (Linux)
vminfo update          # check + install the latest tagged release
vminfo update --check  # check without installing
vminfo update --version v0.1.0
vminfo version --json  # build metadata
vminfo --lang zh       # switch UI language

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

Web dashboard

vminfo --web                      # default: 127.0.0.1:20021
vminfo --web --bind 0.0.0.0 --port 8080 --interval 1s

When binding to all interfaces, startup output now shows friendlier URLs instead of only 0.0.0.0:

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

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.

Endpoints:

• GET /healthz — health check
• GET /api/v1/snapshot — current snapshot JSON
• GET /ws — live WebSocket stream

Self-update

Release builds can update themselves from GitHub Releases:

vminfo update
vminfo update --check
vminfo update --version v0.1.0

Notes:

• Uses the repository configured in build metadata (default: cloudapp3/vminfo)
• Respects GITHUB_TOKEN / GH_TOKEN for higher GitHub API limits
• Update checks are cached at $XDG_CACHE_HOME/vminfo/update-check.json or ~/.cache/vminfo/update-check.json
• vminfo update installs the selected release in place; vminfo update --check only reports status
• Development builds (version=dev) should use --version vX.Y.Z to install a tagged release
• Windows currently supports update --check; in-place self-update is not supported yet

Recent web UI polish:

• Larger overall type scale for easier browser reading
• Resource progress bars use grouped spacing and segmented tracks
• CPU right-side block is vertically centered in the Resources card
• Per-core CPU bars are larger and the extra avg footer has been removed

TUI controls

Key	Action
q / ctrl+c	Quit
?	Toggle help
p	Pause / resume
+ / -	Adjust interval
r	Refresh now
tab	Switch overview / processes
↑ / ↓	Move selection
s	Cycle sort
t	Tree view
/	Filter processes
k	SIGTERM selected process
enter / y	Confirm kill
esc / n	Cancel

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

Library usage

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)
}

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

Platform support

Capability	Linux	macOS	Windows
summary / watch	✅	✅	✅
TUI	✅	✅	✅
Web dashboard	✅	✅	✅
ps / kill	✅	⚠️ stub	⚠️ stub
update --check	✅	✅	✅
update install	✅	✅	⚠️ check-only

TUI requires a real TTY. ps and kill are Linux-only by design.

Build from source

git clone https://github.com/cloudapp3/vminfo.git
cd vminfo
go build -ldflags "\
  -X github.com/cloudapp3/vminfo.Version=v0.1.0 \
  -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 vet ./...
go run ./cmd/vminfo summary --json

Documentation

• docs/CHANGELOG.md

License

MIT

Documentation

Overview

Package vminfo provides host runtime inspection helpers for the vminfo CLI and for external Go programs that need lightweight system snapshots.

Index

• Constants
• Variables
• func CollectAll(ctx context.Context, opts Options) (StaticInfo, RuntimeStats, error)
• func TerminateProcess(ctx context.Context, pid int32) error
• type AppMetadata
  • func Metadata() AppMetadata
• type DiskIOStats
• type InterfaceIO
• type Options
• type ProcessInfo
  • func ListProcesses(ctx context.Context) ([]ProcessInfo, error)
• type RuntimeStats
  • func CollectStats(ctx context.Context, opts Options) (RuntimeStats, error)
• type Snapshot
• type StaticInfo
  • func CollectStatic(ctx context.Context) (StaticInfo, error)
• type TempReading

Constants

const (
	AppName              = "vminfo"
	DefaultDescription   = "Host runtime information toolkit"
	DefaultRepositoryURL = "https://github.com/cloudapp3/vminfo"
	DefaultHomepageURL   = DefaultRepositoryURL
	DefaultSchemaVersion = "v1"
)

const DefaultSampleInterval = time.Second

DefaultSampleInterval is the fallback sampling interval used by runtime collection helpers when Options.SampleInterval is not set.

Variables

var (
	// Version is the application version injected at build time.
	Version = "dev"
	// Commit is the source revision injected at build time.
	Commit = "none"
	// BuildTime is the build timestamp injected at build time.
	BuildTime = "unknown"
	// Channel is the release channel injected at build time.
	Channel     = "dev"
	Repository  = DefaultRepositoryURL
	Homepage    = DefaultHomepageURL
	License     = "MIT"
	Description = DefaultDescription
)

Functions

func CollectAll

func CollectAll(ctx context.Context, opts Options) (StaticInfo, RuntimeStats, error)

CollectAll returns both static host details and sampled runtime metrics. Uses cached static data; reads only dynamic data (mem/swap) fresh each call.

func TerminateProcess

func TerminateProcess(ctx context.Context, pid int32) error

TerminateProcess sends SIGTERM to the given process on Linux and returns an unsupported error on other platforms.

Types

type AppMetadata

type AppMetadata struct {
	Name          string `json:"name"`
	Version       string `json:"version"`
	Commit        string `json:"commit,omitempty"`
	BuildTime     string `json:"build_time,omitempty"`
	Channel       string `json:"channel,omitempty"`
	Repository    string `json:"repository,omitempty"`
	Homepage      string `json:"homepage,omitempty"`
	License       string `json:"license,omitempty"`
	Description   string `json:"description,omitempty"`
	SchemaVersion string `json:"schema_version,omitempty"`
}

AppMetadata describes build and repository metadata for the vminfo CLI.

func Metadata

func Metadata() AppMetadata

Metadata returns normalized application metadata for CLI and embedding use.

type DiskIOStats

type DiskIOStats struct {
	Name       string `json:"name"`
	ReadBytes  uint64 `json:"read_bytes"`
	WriteBytes uint64 `json:"write_bytes"`
	ReadSpeed  uint64 `json:"read_speed,omitempty"`
	WriteSpeed uint64 `json:"write_speed,omitempty"`
	ReadCount  uint64 `json:"read_count,omitempty"`
	WriteCount uint64 `json:"write_count,omitempty"`
	IOPS       uint64 `json:"iops,omitempty"`
}

DiskIOStats holds per-device disk I/O statistics.

type InterfaceIO

type InterfaceIO struct {
	Name     string `json:"name"`
	RxSpeed  uint64 `json:"rx_speed,omitempty"`
	TxSpeed  uint64 `json:"tx_speed,omitempty"`
	IPv4     string `json:"ipv4,omitempty"`
	RxBytes  uint64 `json:"rx_bytes,omitempty"`
	TxBytes  uint64 `json:"tx_bytes,omitempty"`
	RxErrors uint64 `json:"rx_errors,omitempty"`
	TxErrors uint64 `json:"tx_errors,omitempty"`
	RxDrops  uint64 `json:"rx_drops,omitempty"`
	TxDrops  uint64 `json:"tx_drops,omitempty"`
}

InterfaceIO holds per-interface network I/O stats.

type Options

type Options struct {
	SampleInterval time.Duration
}

Options configures runtime collection behavior.

type ProcessInfo

type ProcessInfo struct {
	PID           int32   `json:"pid"`
	PPID          int32   `json:"ppid,omitempty"`
	Name          string  `json:"name,omitempty"`
	User          string  `json:"user,omitempty"`
	State         string  `json:"state,omitempty"`
	CPUPercent    float64 `json:"cpu_percent,omitempty"`
	MemoryPercent float32 `json:"memory_percent,omitempty"`
	RSSBytes      uint64  `json:"rss_bytes,omitempty"`
	Threads       int32   `json:"threads,omitempty"`
	Nice          int32   `json:"nice,omitempty"`
	Uptime        uint64  `json:"uptime,omitempty"`
}

ProcessInfo describes one local process entry returned by ListProcesses.

func ListProcesses

func ListProcesses(ctx context.Context) ([]ProcessInfo, error)

ListProcesses returns local processes on Linux and an unsupported error on other platforms.

type RuntimeStats

type RuntimeStats struct {
	CPU          float64       `json:"cpu"`
	CPUPerCore   []float64     `json:"cpu_per_core,omitempty"`
	CPUCount     int           `json:"cpu_count,omitempty"`
	CPUFreqMHz   float64       `json:"cpu_freq_mhz,omitempty"`
	MemUsed      uint64        `json:"mem_used,omitempty"`
	SwapUsed     uint64        `json:"swap_used,omitempty"`
	DiskUsed     uint64        `json:"disk_used,omitempty"`
	NetIn        uint64        `json:"net_in,omitempty"`
	NetOut       uint64        `json:"net_out,omitempty"`
	NetInSpeed   uint64        `json:"net_in_speed,omitempty"`
	NetOutSpeed  uint64        `json:"net_out_speed,omitempty"`
	Load1        float64       `json:"load1,omitempty"`
	Load5        float64       `json:"load5,omitempty"`
	Load15       float64       `json:"load15,omitempty"`
	TCPCount     uint32        `json:"tcp_count,omitempty"`
	UDPCount     uint32        `json:"udp_count,omitempty"`
	ProcessCount uint32        `json:"process_count,omitempty"`
	Uptime       uint64        `json:"uptime,omitempty"`
	DiskIO       []DiskIOStats `json:"disk_io,omitempty"`
	Temps        []TempReading `json:"temps,omitempty"`
	Interfaces   []InterfaceIO `json:"interfaces,omitempty"`
}

RuntimeStats contains sampled runtime metrics for the local host.

func CollectStats

func CollectStats(ctx context.Context, opts Options) (RuntimeStats, error)

CollectStats samples runtime metrics using the provided options. Uses cached static data; reads only dynamic data (mem/swap) fresh each call.

type Snapshot

type Snapshot struct {
	Static StaticInfo   `json:"static"`
	Stats  RuntimeStats `json:"stats"`
}

Snapshot combines static host metadata with sampled runtime metrics.

type StaticInfo

type StaticInfo struct {
	OS             string `json:"os"`
	Platform       string `json:"platform,omitempty"`
	OSVersion      string `json:"os_version,omitempty"`
	Kernel         string `json:"kernel,omitempty"`
	Arch           string `json:"arch,omitempty"`
	Hostname       string `json:"hostname,omitempty"`
	CPUModel       string `json:"cpu_model,omitempty"`
	CPUCores       uint32 `json:"cpu_cores,omitempty"`
	MemTotal       uint64 `json:"mem_total,omitempty"`
	SwapTotal      uint64 `json:"swap_total,omitempty"`
	DiskTotal      uint64 `json:"disk_total,omitempty"`
	Virtualization string `json:"virtualization,omitempty"`
}

StaticInfo contains host properties that change rarely across samples.

func CollectStatic

func CollectStatic(ctx context.Context) (StaticInfo, error)

CollectStatic reads one set of static host details.

type TempReading

type TempReading struct {
	SensorKey   string  `json:"sensor_key"`
	Temperature float64 `json:"temperature"`
	High        float64 `json:"high,omitempty"`
	Critical    float64 `json:"critical,omitempty"`
}

TempReading represents a single temperature sensor reading.