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

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 fleet of workers. Workers connect to a central manager and can be triggered to execute diagnostic and system introspection commands concurrently. The volli executable can be launched in manager and worker modes, and used to send queries to a manager using either manager or worker profiles.

Results are aggregated and presented via JSON, text tables, or summary output.

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:

  • Manager (serve)
  • Worker
  • CLI (exec)

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-manager – manager daemon.
• volli-worker – worker daemon.

Top-Level Binary Modes

serve (alias: manager)

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

worker

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

exec

• CLI entrypoint for executing diagnostics.
• Supports single-command execution with output formatting.
• Filter targets by worker tags.

Communication Protocol

• QUIC (via Quinn): Multiplexed, encrypted transport.
• JSON messages:
  • Command broadcast
  • Response collection
• Optional authentication: CSK-signed tokens and per-profile secrets.

Output Modes

For CLI execution (exec):

• Text table (default)
• JSON (--format json)
• Pretty JSON (--format json-pretty)
• Summary (--format summary)

Supported Commands

Implemented (exec subcommands)

• ping – Check if a host is reachable.
• trace – Show network path to a host (traceroute).
• dig – Resolve domain names.
• scan – Check open ports.
• curl / http – Fetch a URL and report status/latency.

Planned Network Diagnostics

• dns – Resolve domain names (dig).
• whois – Query domain/IP registration info.
• check – Test TCP/UDP port (nc).
• grpc – Interact with gRPC endpoints (grpcurl).
• flood – Basic HTTP load generator.
• speed – Bandwidth measurement.

Planned System Diagnostics

• space – Disk usage (df).

• health – CPU, Mem, Disk stats.

• audit – Quick security scan:

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

Planned Fleet Metadata

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

Architecture

     [CLI - worker mode]      [CLI - manager mode]
           |                      |
         [Worker]  <-----------> [Manager]
           |                      |
         [Worker]              [Worker]

• CLI can be invoked from any worker.
• Commands are proxied to the manager.
• Manager dispatches to connected workers (the fleet).
• Results are sent back and aggregated.

Configuration

• Default config root is ~/.config/volli (XDG) with fallback to ~/.volli.
• Override with --config-root or VOLLI_CONFIG_DIR.
• Stores manager/worker profiles, secrets, and peer state.

CLI Examples

volli serve --bind 127.0.0.1
volli worker 1.2.3.4:4242
volli exec ping 8.8.8.8
volli exec trace example.com --format json
volli exec scan 10.0.0.5 --ports 22,80,443 --format table
volli exec dig example.com AAAA --format summary
volli exec curl https://example.com --method GET --format json-pretty
# increase logging
volli -v serve --bind 127.0.0.1
volli -vv worker 1.2.3.4:4242
volli --quiet exec 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 managers locally

When you start volli serve without specifying ports it binds to TCP 4242 and QUIC 4242 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 manager 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.