Metadata-Version: 2.4
Name: vssh
Version: 4.1.3
Summary: vssh - installs Go binary
Author-email: MeshPOP <mpop@mpop.dev>
License: MIT
Project-URL: Homepage, https://github.com/meshpop/vssh
Keywords: ssh,scp,remote
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# vssh

[![PyPI](https://img.shields.io/pypi/v/vssh)](https://pypi.org/project/vssh/)

**SSH/SCP CLI - Go binary installer**

```bash
pip install vssh
vssh  # Auto-downloads Go binary on first run
```

This package automatically downloads and installs the native Go binary for your platform.
[![Python](https://img.shields.io/pypi/pyversions/vssh)](https://pypi.org/project/vssh/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

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

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

```bash
export VSSH_SECRET=your-shared-secret
vssh server

# Or install as a systemd service:
vssh install
```

Generate a strong secret:
```bash
python3 -c "import secrets; print(secrets.token_hex(32))"
```

### 2. Configure the client

With [wire](https://github.com/meshpop/wire) mesh VPN, vssh auto-discovers all nodes — no client config needed.

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

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

---

## CLI Reference

### Fleet status

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

### Remote execution

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

### File transfer

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

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

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

```json
{
  "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](https://github.com/meshpop)
