sshctl

A unified CLI and Model Context Protocol (MCP) server for cross-platform SSH remote execution, passwordless key management, Windows Session 0 interactive desktop process launching, and SFTP file transfers.

---

Architecture

Terminal / Human (CLI)             AI Agent (Claude / Antigravity)
       │                                         │
       ▼                                         ▼
  sshctl (bin/sshctl.js)               MCP Protocol (stdio JSON-RPC)
       │                                         │
       └──────────────────┬──────────────────────┘
                          ▼
                   Core SSH Engine
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
   Connection Pool    PowerShell/UTF-16LE   SFTP Channel
   (60s idle reuse)   (Session 0 / 8K limit) (FastPut / FastGet)
          │               │               │
          └───────────────┼───────────────┘
                          ▼
                  Remote Target Host
            (Windows / Linux / macOS)

---

Features

• Dual-Mode: Run interactively via CLI (sshctl) or as an automated MCP server (sshctl mcp).
• Zero Local Client Shell Dependencies: Pure TypeScript with ssh2. Does not require WSL, Git Bash, sshpass, iconv, or local ssh binaries.
• Automated PowerShell Command Encoding: Converts Windows command bodies to Base64 UTF-16LE strings (powershell.exe -EncodedCommand), removing quote escaping errors.
• Session 0 Desktop Handoff (--desktop): Launches Windows GUI applications directly onto the logged-in user's interactive desktop (Session 1) via Task Scheduler.
• 8,191-Character Auto-Fallback: Automatically detects when PowerShell payloads exceed the cmd.exe command length limit, uploading a temporary script via SFTP with execution and cleanup.
• Connection Pooling: Reuses SSH2 connections per user@host:port with 60-second idle timeouts.
• Profiles & Secret Resolution: Store targets in ~/.sshctl/profiles.json, resolving environment variables (env:VAR_NAME) without storing plain text passwords in chat logs.

---

Quick Start

1. Build

cd claude/sshctl
npm install
npm run build
npm test        # 43 unit and integration tests

2. CLI Usage

# List profiles
sshctl profiles

# Test connectivity and probe remote OS
sshctl test my-profile

# Run remote command
sshctl exec my-profile "hostname && dir"

# Launch GUI app on Windows active desktop
sshctl exec my-profile "calc.exe" --desktop

# Upload/Download files via SFTP
sshctl push my-profile local.txt /remote/path/file.txt
sshctl pull my-profile /remote/path/file.txt local.txt

# Generate Windows OpenSSH installer 1-liner
sshctl bootstrap-rdp --admin

3. Register as MCP Server

sshctl implements the standard Model Context Protocol (MCP). Any MCP client automatically discovers all tools, arguments, and prompts over stdio JSON-RPC without needing external configuration files.

Claude Code CLI

claude mcp add sshctl -- node "/path/to/sshctl/dist/index.js"

Claude Desktop (claude_desktop_config.json) / Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "sshctl": {
      "command": "node",
      "args": ["/path/to/sshctl/dist/index.js"]
    }
  }
}

Google Antigravity

To enable Antigravity's lazy-loading schema discovery:

npm run export:schemas

This automatically writes tool definition JSONs and instructions.md to ~/.gemini/antigravity/mcp/sshctl/.

---

MCP Tools Reference

• ssh_list_profiles: List profiles from ~/.sshctl/profiles.json.
• ssh_test_connection: Probe SSH connectivity & detect target OS.
• ssh_clear_known_hosts: Clear stale entries from ~/.ssh/known_hosts.
• ssh_exec: Execute remote commands with Base64 UTF-16LE, Session 0 bypass (desktop: true), and output capping.
• ssh_setup_passwordless: Deploy ed25519 key to Linux (~/.ssh/authorized_keys) or Windows (administrators_authorized_keys with strict ACLs).
• ssh_remove_passwordless: Revoke public key or clear all keys.
• ssh_upload_file: Upload file via SFTP.
• ssh_download_file: Download file via SFTP.
• ssh_generate_rdp_bootstrap: Generate OpenSSH installation 1-liner.

---

Technical Documentation

For details on PowerShell Base64 encoding, the 8,191-character boundary fallback, Session 0 bypass mechanism, and error code tables, see docs/REFERENCE.md.

---

License

MIT