Metadata-Version: 2.4
Name: vssh
Version: 4.2.1
Summary: Python SDK for the vssh AI-native remote execution daemon
Project-URL: Homepage, https://github.com/meshpop/vssh
Project-URL: Repository, https://github.com/meshpop/vssh
Author: MeshPop
License: MIT
Keywords: ai-agents,mcp,remote-execution,tailscale,vssh
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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](docs/WHY_VSSH.md).

**Out of scope here:** operating the VPN mesh itself and fleet-wide monitoring dashboards—use [Wire](https://github.com/meshpop/wire) and [mpop](https://github.com/meshpop/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)**](https://github.com/meshpop/wire/blob/main/docs/CURRENT_STATE.md) — versions, PyPI, architecture, MCP, deferred work  
- [Why vssh](docs/WHY_VSSH.md)
- [Python SDK](docs/PYTHON_SDK.ko.md)
- [Codex orchestration notes](docs/CODEX_ORCHESTRATION.md)  
- [Public repository audit](docs/PUBLISHING_AUDIT.md)  
- [한국어 README](README.ko.md)  
- [CHANGELOG.md](CHANGELOG.md)  
- [SECURITY.md](SECURITY.md)  
- [HELP.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

```bash
# 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>    Upload through native daemon
vssh get <src> <dst>    Download through native daemon
vssh exec <node> <cmd>  Alias for native run
vssh list               List all nodes
vssh status             Show dashboard
vssh doctor [--json]    Diagnose local setup
vssh version            Show version
vssh help               Show help
```

## Dashboard

```
  vssh dashboard

    SERVER   IP               LOAD   MEM  DISK  UPTIME
  --------------------------------------------------------
  ● web1     192.0.2.10       0.15    8%   40%  48 days
  ● web2     192.0.2.11       0.77    6%   63%  100 days
  ● db1      192.0.2.20       1.53    9%   30%  78 days
  
  3/3 online
```

## Execution Flow

The target product flow is:

```text
vssh client
  -> Tailscale IP / MagicDNS
  -> vssh daemon
  -> typed exec/file/job/service APIs
  -> structured evidence
```

There is deliberately no OpenSSH wrapper command. If a node already has sshd
and all you need is a shell, use `ssh` directly.

## Connection Flow

vssh tries multiple endpoints in order:

1. **Tailscale / VPN IP** - Most reliable when private network is up
2. **LAN IP** - Same local network
3. **Public IP** - Fallback for remote access

## Data Sources

Node discovery:

1. **Wire daemon** - If Wire VPN is running
2. **Wire coordinator** - If coordinator URL is configured
3. **Tailscale** - If Tailscale is running
4. **Config file** - Manual server list (~/.vssh/servers.json)
5. **Cache** - Previously discovered nodes

## Configuration

Servers config: `~/.vssh/servers.json`

```json
{
  "web1": {
    "ip": "192.0.2.10",
    "user": "deploy",
    "tags": ["linux", "web"],
    "capabilities": ["docker"]
  },
  "gpu1": {
    "ip": "192.0.2.20",
    "user": "ubuntu",
    "tags": ["linux", "gpu", "ollama"],
    "capabilities": ["cuda", "ollama"],
    "monitor_port": 8721
  },
  "mac1": {
    "ip": "192.0.2.30",
    "user": "admin",
    "os": "darwin",
    "tags": ["mac", "browser"],
    "capabilities": ["browser"]
  }
}
```

Do not commit real `~/.vssh/servers.json`, Wire config, hostnames, VPN IPs, or secrets. Keep local inventory files outside the repository and use example values in documentation.

`vssh.hosts.list` returns these fields as routing metadata for agents, together
with inferred capabilities and a health object.

VSSH does not embed a monitoring daemon. If you run a separate monitor such as
`meshclaw monitor` or `mpop agent`, add either `monitor_port` or `monitor_url`
per host. Agent tools can then request `include_health: true` to merge live
`/api/node/status` data into the host record before routing.

User mapping: `~/.wire/users.json`

```json
{
  "web1": "deploy",
  "db1": "postgres",
  "app1": "deploy"
}
```

## Native Protocol

vssh can work without sshd using its native protocol:

```bash
# On server
vssh server           # Start vssh server on :48291

# On client
vssh shell web1         # Native shell
vssh run web1 "df -h"   # Native exec
vssh put file web1:/tmp # Native upload
vssh get web1:/tmp/x .  # Native download
```

Set `VSSH_SECRET` on both client and server before exposing the native server. See [SECURITY.md](SECURITY.md).

## Codex / Runtime Usage

VSSH can be used as an execution substrate for AI-native runtimes:

- route work to nodes by name
- preserve quoted, piped, and multiline commands
- return `stdout`, `stderr`, `exit_code`, duration, transport, and endpoint attempts
- record evidence in Matrix events, task ledgers, or audit logs

Run the MCP server:

```bash
vssh mcp
```

Python SDK:

```bash
python -m pip install vssh
```

```python
from vssh import VSSH

client = VSSH(secret="change-me")
facts = client.facts("web1")
fleet = client.facts_many(["web1", "db1"])
results = client.exec_many(["web1", "db1"], "uptime")
job = client.job_start("web1", "long-running-command")
doctor = client.doctor()
```

The Python SDK is a client layer for AI agents and automation. It calls the
installed Go `vssh` binary instead of reimplementing the daemon protocol.

Agent-facing MCP tools:

| Tool | Purpose |
|------|---------|
| `vssh_doctor` | Diagnose binary, secret source, wire config, peers, and MCP readiness |
| `vssh_hosts_list` | List known hosts for routing |
| `vssh_exec_safe` | Execute read/diagnostic commands with policy blocking |
| `vssh_exec` | Execute with policy checks and optional `allow_dangerous` |
| `vssh_route_select` | Select the best host by capability, tag, and health |
| `vssh_exec_routed` | Route first, then execute with policy/evidence |
| `vssh_policy_check` | Classify a command before execution |
| `vssh_status`, `vssh_list` | Status and peer inventory |

Commands matching destructive/service-impacting patterns such as `rm -rf`,
`shutdown`, `reboot`, `docker rm`, `kubectl delete`, and `systemctl restart`
are blocked unless the caller sets `allow_dangerous: true` after explicit human
approval. Every execution response is an evidence envelope with timestamps,
policy decision, target, command, timeout, and the structured execution result.

`vssh_hosts_list` returns agent-friendly records:

```json
{
  "name": "gpu1",
  "addresses": {"vpn": "192.0.2.20"},
  "user": "ubuntu",
  "tags": ["gpu", "linux", "ollama"],
  "capabilities": ["cuda", "gpu", "linux", "ollama"],
  "health": {"status": "unknown", "reason": "no live health signal"}
}
```

Routed execution lets agents ask for capabilities instead of hard-coding a host:

```json
{
  "required_capabilities": ["cuda", "ollama"],
  "preferred_tags": ["gpu"],
  "avoid_health": ["offline", "degraded"],
  "include_health": true,
  "command": "ollama list",
  "timeout_seconds": 20
}
```

VSSH evaluates candidates, records the route decision, checks command policy,
and then executes on the selected host.

See [docs/CODEX_ORCHESTRATION.md](docs/CODEX_ORCHESTRATION.md).

## Public Repository Hygiene

This repository should contain source and public examples only. Release binaries are published as GitHub Release assets, not committed to Git. See [docs/PUBLISHING_AUDIT.md](docs/PUBLISHING_AUDIT.md).

## Building

```bash
make build      # Build vssh
make install    # Install to /usr/local/bin
make release    # Build for all platforms
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## Requirements

- Go 1.21+ (for building)
- No SSH client required for native daemon mode

## License

MIT
