Metadata-Version: 2.4
Name: vssh
Version: 3.2.2
Summary: Secure SSH/SCP tool with Tailscale failover and P2P transport
Author-email: MeshPOP <hello@meshpop.dev>
License: MIT
Project-URL: Homepage, https://github.com/meshpop/vssh
Project-URL: Repository, https://github.com/meshpop/vssh
Keywords: ssh,scp,tailscale,p2p,vpn,remote
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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

```bash
# 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

```bash
# 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
```

```json
{
  "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
