A stable JSON envelope separates stdout, stderr, exit code, timing, signals, and timeout state.
Native OpenSSH. Ready for agents.
SSH, With An Operating Contract
Keep the SSH commands you already know. Add guardrails before execution, structured results after it, privacy-safe audit metadata, and file transfer that fails as one operation.
Native OpenSSHExact Exit CodesZero Runtime DependenciesPublic Source Code
Built by Robert E. Beckner III for developers and agents who need remote work to stay explicit and inspectable.
Native commands. Structured results.
npm install -g @light-merlin-dark/vsshvssh config setupvssh doctorvssh --json 'systemctl is-active api'vssh upload --mode 600 ./app.env /etc/app/app.envProduct
What You Stop Rebuilding In Every Project
Catastrophic-command checks run before a connection is opened, while familiar remote commands stay familiar.
Uploads can set remote permissions as part of one operation, with connection reuse enabled by default.
The Contract
A Thin Layer That Earns Its Place
VSSH delegates transport to native OpenSSH and adds only the workflow guarantees that are missing from plain ssh and scp.
Structured, Not Abstracted
Use the Linux, Docker, systemd, and shell commands you already know. Add --json only when a script or agent needs a stable result contract.
Native All The Way Down
Host verification, known_hosts, SSH-agent access, stdin, stdout, stderr, signals, and remote exit behavior come directly from OpenSSH.
Auditable Without Surveillance
Owner-only records store command hashes and outcomes—not command text, output, credentials, or transferred file contents.
Raw SSH
Excellent Transport. Everything Around It Is Yours.
Scripts must define their own output envelope and keep stdout, stderr, timing, and failures unambiguous.
Safety policy, connection diagnostics, audit behavior, and upload permission changes become project-local shell glue.
Connection reuse is available, but every caller has to configure and preserve the multiplexing contract.
With VSSH
The Same Transport, With A Repeatable Operator Contract.
Raw mode preserves native streams and exit codes; JSON mode returns one bounded, parseable result.
Guardrails run before the network, and privacy-safe metadata records what happened without storing content.
Doctor, core transfers, upload modes, timeouts, and control reuse behave consistently across projects.
FAQ
Common Questions About VSSH
The precise boundary between native OpenSSH and the small automation layer VSSH adds around it.
VSSH is an open-source CLI that delegates remote execution and transfer to native OpenSSH, then adds guardrails, structured results, diagnostics, connection reuse, and privacy-safe audit metadata.
Use plain ssh when transport is all you need. Use VSSH when agents and scripts also need consistent safety checks, JSON output, diagnostics, transfers, and a privacy-safe audit trail.
No. Native ssh and scp remain the transport. VSSH preserves their host verification, known_hosts policy, SSH-agent access, streams, signals, and exit behavior.
Agents already know shell and SSH commands. VSSH lets them keep that knowledge while adding machine-readable results, predictable failures, preflight guardrails, and command discovery.
Only owner-readable metadata: timestamp, transport, duration, exit status, command byte length, and a SHA-256 command hash. It never stores command text or output.
No. VSSH 2 is a focused, dependency-free CLI. A small set of legacy aliases remains for deployed scripts, but it is not a plugin platform or MCP server.
Yes. Uploads and downloads use native scp for files or directories. Uploads can also set an octal remote mode and fail the whole operation if the permission change fails.
VSSH preserves the remote exit code. Timeouts return 124, guard blocks return 126, and JSON mode includes separated stdout and stderr with the exact failure state.