vssh 3.2.3

Secure SSH/SCP tool with Tailscale failover, P2P transport, and MCP server

vssh — Distributed Command & File Transport

vssh is a distributed command and file transport daemon for server meshes. RPC, file transfer, command execution and terminal access — every node runs the same daemon and acts as both client and server.

v3.2.2 | Single file (~3500 lines) | No dependencies | 14-node peer mesh

Installation

# Install vssh
curl -fsSL https://mpop.dev/vssh | bash

# Check connection status
vssh status

Every node runs as both client and server. Primary transport: Wire mesh. Automatic fallback: Tailscale mesh.

What vssh is

Cluster transport protocol Unifies RPC, file transfer, command execution and terminal access in a single daemon.

Every node is a peer The same daemon runs on every node. Each node acts as both client and server. No central coordinator.

Transport-agnostic Runs over Wire VPN, Tailscale, or direct P2P connections. vssh does not depend on a specific VPN.

Name-based access Connect to servers by name (g1, v1, d1) instead of IP addresses.

Architecture

AI / CLI
   |
   v
mpop (control plane)
   |
   v
vssh (command + data bus)    <-- you are here
   |
   v
network fabric
   +-- Wire mesh (10.99.x.x)
   +-- Tailscale mesh (100.x.x.x, automatic failover)
   +-- direct P2P (NAT hole-punch)

Protocol

Single TCP connection on port 48291. All commands follow CMD:auth:args format:

Command	Format	Purpose
RPC	RPC:auth:method:payload_len	Remote procedure call
PUT	PUT:auth:path:size:md5	Upload file
GET	GET:auth:path	Download file
SSH	SSH:auth:command	Execute command
SESSION	SESSION:auth	Persistent connection
TAR_UP	TAR_UP:auth:path:size:md5:comp	Directory transfer
PUTZ	PUTZ:auth:path:csize:osize:md5	Compressed upload
MPUT	MPUT:auth:count	Multi-file upload
INFO	INFO:auth	Node info (JSON)

Key Commands

Command	Description
vssh status	Connection status to all servers with latency
vssh exec SERVER "cmd"	Execute a command on a remote server
vssh put SERVER local remote	Upload file (MD5 skip, zlib compression)
vssh get SERVER remote local	Download a file
vssh sync SRC DST path	Sync files directly between servers (delta)
vssh tunnel SERVER LP RP	Port forwarding tunnel
vssh speed-test SERVER	Test transfer speed
vssh p2p-status	Check NAT hole-punch capability
vssh keys	Manage SSH keys and secrets

Full CLI reference

Cluster status

Command	Description
vssh status	Connection status to all servers with latency
vssh stats [days]	Transfer statistics

Remote execution

Command	Description
vssh ssh <host> "cmd"	Execute command on remote server (PTY)
vssh <host>	Interactive terminal (shortcut for session)
vssh session <host>	Persistent terminal session
vssh rpc <host> <method> [json]	Remote procedure call (12 methods)
vssh rpc-list <host>	List available RPC methods
vssh info <host>	Node info as JSON

File transfer

Command	Description
vssh put <local> <host>:<remote>	Upload (MD5 skip, zlib compression)
vssh get <host>:<remote> <local>	Download (auto multi-conn for large files)
vssh sync <local_dir> <host>:<remote>	Sync files directly between two servers (delta)
vssh mput <host>:/path file1 file2	Multi-file upload (single connection)
vssh fast <local> <host>:<remote>	Auto-select best transfer method
vssh p2p <local> <host>:<remote>	P2P direct transfer (NAT hole-punch)
vssh rsync <local> <host>:<remote>	Delta sync (only changed blocks)
vssh pipe <host>:<path>	Pipe stdin to remote file / remote cmd to stdout

Server

Command	Description
vssh server	Start daemon
vssh help	Show usage

Usage Examples

# Run a command on server g1
vssh exec g1 "df -h"

# Upload a script to v1
vssh put v1 ./deploy.sh /opt/scripts/deploy.sh

# Download logs from d1
vssh get d1 /var/log/app.log ./app.log

# Sync a directory between servers
vssh sync g1 g2 /opt/app/

# Query cluster state
vssh info g1

# RPC call
vssh rpc g1 get_memory
vssh rpc g2 docker_containers

Performance

Direct P2P transfers bypass traditional SSH bottlenecks.

Mode	Throughput	Notes
VPN relay (standard)	~3 MB/s	WireGuard overhead
P2P single stream	~25 MB/s	NAT hole-punch → direct TCP
P2P 4 streams	~53 MB/s	Production measured
P2P 8 streams	~80+ MB/s	Maximum throughput

No SSH overhead. Parallel chunked transfer with adaptive chunking.

Network resilience

vssh is transport-agnostic. If Wire VPN is unavailable, vssh automatically falls back to Tailscale.

1. Wire VPN (10.99.x.x) — primary, WireGuard mesh
2. Tailscale (100.x.x.x) — automatic fallback when Wire is down
3. Direct P2P — NAT hole-punch for high-throughput transfers

Mapping stored in ~/.vssh/tailscale_map. Failover cache avoids repeated timeouts.

Security

• HMAC-SHA256 authentication (60s timestamp window)
• Wire VPN layer: WireGuard ChaCha20-Poly1305 encryption
• P2P mode: TLS 1.2/1.3 (ECDHE + ChaCha20/AES-GCM)
• No OpenSSH dependency

Cluster (14 nodes)

Server	Type	Platform
v1-v4	VPS	Linux
g1-g4	GPU	Linux
d1-d2	Bare Metal	Linux
m1	workstation	macOS
n1	VPS	Linux
s1-s2	Synology NAS	DSM 7

Ports

Port	Purpose
48291	Main (TCP)
48295	P2P signaling (TCP)
48296	P2P relay (UDP)

MCP Integration

Claude can operate servers through vssh using MCP tools.

Claude → MCP → vssh → servers

{
  "mcpServers": {
    "vssh": {
      "command": "vssh",
      "args": ["mcp"]
    }
  }
}

MCP Tools (9): vssh_status, vssh_exec, vssh_put, vssh_get, vssh_sync, vssh_speed_test, vssh_p2p_status, vssh_tunnel, vssh_keys

License

MIT