vssh 4.0.0

[DEPRECATED - Use Go version] Secure SSH/SCP tool

vssh

⚠️ DEPRECATED: This Python package is no longer maintained. Please use the Go version instead:

# macOS
brew install meshpop/tap/vssh

# Linux
curl -sSL https://github.com/meshpop/vssh/releases/latest/download/vssh-linux-amd64 -o /usr/local/bin/vssh && chmod +x /usr/local/bin/vssh

GitHub: https://github.com/meshpop/vssh

Fast SSH alternative for server fleets. One shared secret. No key management.

pip install vssh

Pure Python standard library. No external packages. Linux and macOS.

---

Why vssh?

	SSH	vssh
Authentication	Per-server public keys	One shared HMAC secret
Add a new server	Generate + copy key	Just set the same secret
Revoke access	Remove key from every server	Rotate secret once
Connection setup	Full handshake (~200–400ms)	Token check (~1ms)
Server discovery	IPs / DNS	wire mesh auto-discovery
Fleet health	None	vssh status — all nodes
AI management	✗	✓ MCP integration

---

How it works

Each server runs a persistent daemon on TCP port 48291. Every request includes an HMAC-SHA256 time-based token derived from the shared secret — no public key cryptography, no handshake overhead.

┌──────────────────────────────────────┐
│  Fleet                               │
│  ┌──────┐  ┌──────┐  ┌──────┐        │
│  │ web1 │  │ web2 │  │ db1  │  ...   │
│  │:48291│  │:48291│  │:48291│        │
│  └──┬───┘  └──┬───┘  └──┬───┘        │
│     └─────────┴─────────┘            │
│          wire / VPN                  │
└─────────────────┬────────────────────┘
                  │ TCP :48291
           ┌──────┴──────┐
           │ vssh client  │
           └─────────────┘

---

Setup

1. Install and start the daemon on each server

export VSSH_SECRET=your-shared-secret
vssh server

# Or install as a systemd service:
vssh install

Generate a strong secret:

python3 -c "import secrets; print(secrets.token_hex(32))"

2. Configure the client

With wire mesh VPN, vssh auto-discovers all nodes — no client config needed.

For standalone use, create ~/.vssh/config:

web1=192.168.1.10
web2=192.168.1.11
db1=192.168.1.20
SECRET=your-shared-secret

---

CLI Reference

Fleet status

vssh status           # All nodes — online/offline, latency
vssh status --full    # Status + disk, memory, load

Remote execution

vssh web1 "df -h"                 # Run command
vssh web1                         # Interactive shell
vssh web1 "df -h && free -h"      # Chained commands

File transfer

vssh put  ./nginx.conf web1:/etc/nginx/    # Upload
vssh get  web1:/var/log/app.log ./         # Download
vssh sync ./config/ web1:/etc/app/         # Sync directory
vssh rsync <local> <host>:<remote>         # Delta sync (changed blocks only)

Auto-compresses text files. Skips upload if remote file is identical (MD5 check).

RPC — typed JSON data

vssh rpc web1 get_disk
vssh rpc web1 get_processes '{"n": 5, "sort": "mem"}'
vssh rpc-list web1               # List all available methods

Method	Returns
get_disk	Disk usage
get_memory	Memory stats
get_load	Load averages
get_processes	Top processes
get_gpu	GPU VRAM, utilization, temp
get_logs	Log file or journalctl
list_services	Running systemd services
restart_service	Restart nginx / docker / postgresql / redis
docker_containers	Docker container list
file_read / file_write	File operations

Other

vssh speed-test web1             # Measure transfer speed
vssh history [count] [filter]    # Command history
vssh stats [days]                # Transfer stats
vssh pipe-up web1:/path          # Pipe stdin to remote file
vssh pipe-down web1:"cmd"        # Pipe remote output to stdout

---

Tailscale Failover

If a node's primary VPN IP is unreachable, vssh automatically tries the Tailscale IP:

1. Try wire VPN IP (1.5s timeout)
2. Fall back to Tailscale IP, cache for 60s
3. After 60s: retry wire — if recovered, clear failover

The failover map is built automatically by cross-referencing tailscale status with wire peers.

---

AI Management via MCP

{
  "mcpServers": {
    "vssh": { "command": "vssh-mcp" }
  }
}

"Check which servers are online and show me disk usage" "Deploy the new config to all web servers and reload nginx" "What's using the most memory on db1?"

MCP Tools

Tool	Description
vssh_status	Fleet status — all nodes, latency
vssh_exec	Run command on remote server
vssh_put / vssh_get	Upload / download file
vssh_sync	Sync directory
vssh_speed_test	Transfer speed
vssh_tunnel	Port-forward tunnel
vssh_keys	Show secret and server list

---

MeshPOP Stack

mpop     Fleet orchestration — monitor, manage, automate
vssh     Authenticated transport — remote exec, file transfer  ← this
wire     Encrypted mesh VPN — connects all nodes

---

License

MIT — MeshPOP