vssh

AI-native remote execution daemon and protocol for Tailscale/private networks.

VSSH is designed for two audiences:

• operators who need sshd-free execution on private nodes
• Codex/LLM/runtime orchestrators that need typed execution APIs, long-running jobs, policy, and machine-readable evidence

Scope

vssh is a standalone remote execution agent product. Its core value is the native vssh server daemon path: command execution, files, jobs, policy, and evidence over a private network such as Tailscale.

vssh is not an OpenSSH wrapper. Tailscale + sshd already handles normal remote shell, so the product surface stays focused on the native daemon path.

Why Use vssh

Use vssh when the operator is an AI agent or automation runtime, not a human typing into a terminal.

vssh is better than plain SSH when you need:

• sshd-free execution on private nodes
• structured stdout/stderr/exit/duration evidence
• policy checks before risky actions
• durable jobs, logs, cancellation, and artifact collection
• typed server APIs for facts, services, logs, GPU/model state, and health

If the feature is only "SSH, but shorter", it does not belong in vssh. See Why vssh.

Out of scope here: operating the VPN mesh itself and fleet-wide monitoring dashboards—use Wire and mpop for those layers.

Implementation note: internal/adapter is discovery-oriented (Probe over configured paths). The product direction is to make internal/server the first-class execution path and keep internal/ssh for discovery helpers and legacy internals only.

Documentation

• Full stack snapshot (Wire + mpop + vssh) — versions, PyPI, architecture, MCP, deferred work
• Why vssh
• Python SDK
• Codex orchestration notes
• Public repository audit
• 한국어 README
• CHANGELOG.md
• SECURITY.md
• HELP.md

Features

• Native protocol - sshd-free mode through vssh server
• AI-oriented execution - structured stdout/stderr/exit/duration/evidence
• Job semantics - designed for long-running work, cancellation, and logs
• File/artifact APIs - transfer and collect files without broad shell UX
• Policy hooks - classify and gate actions before execution
• Name-based access - route by node name rather than raw addresses
• Auto-discovery - finds nodes via Tailscale, config, or legacy sources
• Runtime-oriented results - MCP paths return structured execution evidence for Codex/LLM orchestration

Quick Start

# Install
curl -fsSL https://raw.githubusercontent.com/meshpop/vssh/main/install.sh | bash

# Run native daemon on a node
VSSH_SECRET=change-me vssh server

# From a client on the same private network
VSSH_SECRET=change-me vssh run web1 "df -h"

# Show status
vssh                 # Dashboard
vssh list            # List all nodes
vssh doctor --json   # Diagnose binary, secret, config, peers, and MCP readiness

Commands

vssh                    Show dashboard (default)
vssh server             Run native daemon
vssh <node>             Open native shell
vssh run <node> <cmd>   Run command through native daemon
vssh run-many <nodes> <cmd>  Run command across comma-separated nodes
vssh rpc <node> <method> [json]  Call typed daemon RPC
vssh rpc-many <nodes> <method> [json]  Call RPC across nodes
vssh facts <node>       Return typed daemon facts
vssh facts-many <nodes> Return facts across comma-separated nodes
vssh job-start <node> <cmd>  Start a long-running daemon job
vssh job-status <node> <id>  Return job status
vssh job-logs <node> <id>    Return job logs
vssh job-cancel <node> <id>  Cancel a job
vssh shell <node>       Open native shell
vssh put <src> <dst>    

... [View full README on GitHub](https://github.com/meshpop/vssh#readme)