Volli – a distributed CLI tool for network and system diagnostics across a fleet of nodes.

Name

volli is a tactical, lightweight tool that allows you to launch fast, distributed diagnostics and system checks from a central command.

Overview

volli is a fast, lightweight Rust CLI tool for performing coordinated diagnostics across a distributed cluster of nodes. Nodes connect to a central coordinator and can be triggered to execute diagnostic and system introspection commands concurrently. The volli executable can be launched in both server and agent modes, and used to send queries to a server or agent.

Results are aggregated and presented via JSON, text table, or TUI.

Design Goals

• Single static binary: Lightweight, no dependencies.

• Fast: Async by default using Tokio.

• Self-hosted: No SaaS, private mesh or hub-and-spoke model.

• Secure: Encrypted communication (TLS/QUIC).

• Flexible Execution Modes:

  • Server (coordinator)
  • Node (agent)
  • CLI (client)

Workspace Layout

The project is organized as a Cargo workspace containing several crates:

• volli-core – shared message types and utilities.
• volli – command line interface binary.
• volli-server – coordinator daemon (placeholder).
• volli-agent – agent daemon (placeholder).

Top-Level Binary Modes

serve

• Long-running daemon.
• Listens for connections from nodes.
• Receives and broadcasts diagnostics commands.
• Aggregates results.

agent

• Long-running daemon connected to a coordinator launched using serve.
• Waits for commands to execute locally.
• Can proxy commands from a local CLI back to the server.

run

• CLI entrypoint for executing diagnostics.
• Supports both single-command and multi-check execution.
• Two supported modes:
  • One-shot CLI mode – filter hosts and checks explicitly; customize output format.
  • Interactive mode – TUI-guided session for selecting hosts and checks.

Communication Protocol

• QUIC (via Quinn): Multiplexed, encrypted transport.
• JSON messages:
  • Command broadcast
  • Response collection
• Optional authentication: Node keys + signed config.

Output Modes

For one-shot CLI execution (run):

• Text Table (default for humans)
• JSON (for scripting/piping)
• TUI (ncurses-style real-time paneled UI)

For interactive mode (volli run --interactive):

• Always uses a rich TUI interface for target selection and result visualization.

Supported Commands

Network Diagnostics

• ping – Check if a host is reachable.
• trace – Show network path to a host (traceroute).
• dns – Resolve domain names (dig).
• scan – Check open ports (nmap).
• whois – Query domain/IP registration info.
• check – Test TCP/UDP port (nc).
• http – Fetch URL, report status & time (curl).
• grpc – Interact with gRPC endpoints (grpcurl).
• flood – Basic HTTP load generator.
• speed – Bandwidth measurement.

System Diagnostics

• space – Disk usage (df).

• health – CPU, Mem, Disk stats.

• audit – Quick security scan:

  • Open ports
  • SUID files
  • sudo rules
  • Unsafe permissions

Cluster Metadata

• info – OS, uptime, hostname, public IP.
• nodes – List registered nodes.
• reach – Check node availability & latency.

Architecture

     [CLI - node mode]      [CLI - server mode]
           |                     |
         [Node]  <----------->  [Server]
           |                     |
         [Node]               [Node]

• CLI can be invoked from any node.
• Commands are proxied to the server.
• Server dispatches to connected nodes.
• Results are sent back and aggregated.

Configuration

• ~/.volli/config.toml or --config path
• Contains server address, auth keys, node name/tag.

CLI Examples

volli serve --bind 127.0.0.1:4242
volli node --connect 1.2.3.4:4242
volli run ping 8.8.8.8
volli run trace example.com --output tui
volli run audit --output json
volli run --hosts 10.0.0.1,10.0.0.2 --include ping,dns,http,audit --output table
volli run --interactive
# increase logging
volli -v serve --bind 127.0.0.1:4242
volli -vv agent --connect 1.2.3.4:4242
volli --quiet run ping 8.8.8.8

Use -v to increase verbosity, -vv for trace-level output and --quiet for warnings only.

Shell completions

Generate a completion script for your shell:

volli completions bash > /usr/local/share/bash-completion/volli

Running multiple coordinators locally

When you start volli serve without specifying ports it binds to TCP 4242 and QUIC 4243 on 127.0.0.1. Launching a second instance with the same ports will fail even if you bind to a different loopback address because the first process owns the port. Use --tcp-port and --quic-port to assign unique ports when running more than one coordinator on the same host. Example:

volli serve --bind 127.0.0.2 --tcp-port 4252 --quic-port 4253 --join <TOKEN>

This spec serves as the initial foundation for implementation. Each module (network, system, TUI, transport) can be built independently and iterated on.