pix-ssh

Pi tool — ssh_run: run a command through a remote host's configured SSH shell, optionally through POSIX sudo.

[!IMPORTANT] Basic Windows cmd, Windows PowerShell, and pwsh commands may work through the configured SSH shell, but support is best-effort. Shell selection, complex quoting, PowerShell error/stream/encoding semantics, interactive prompts, and Windows administrator/UAC elevation are not covered. The agent should back away when correctness depends on those limits. sudo: true supports POSIX sudo only.

What it does

Registers the ssh_run tool — run a command through the configured SSH shell on a remote machine, behind the same permission dialog pix-sudo uses (shared overlay from @xynogen/pix-pretty).

• Initial + privileged calls → Allow/Deny approval, 60-second auto-deny timeout.
• Non-privileged calls → may auto-approve during the 15-minute per-host window, or in YOLO mode when no password is missing; each auto-approval emits a notification.

Output is truncated to 50 KB / 2000 lines. Non-interactive (RPC/JSON) mode blocks the tool immediately.

Parameters: action ("command" default · "file" · "info"), host as [user@]host[:port] (e.g. [email protected]:2222), command, optional sudo (run through POSIX sudo as root), optional reason.

action: "info" — SSH config, no connection

Lets the agent discover hosts without reading ~/.ssh/config itself. Read-only: no connection, no approval dialog, no password.

• No host → lists configured host aliases from ~/.ssh/config and every file it pulls in via Include (glob + relative paths resolved OpenSSH-style, cycle-guarded). Wildcard-only patterns (Host *) are skipped. Each row shows alias → user@hostname:port plus via <ProxyJump> when set.
• With host → runs ssh -G <host> and reports the effective HostName/User/Port/ProxyJump/IdentityFile for that target (alias resolution, Match, and Include all handled by OpenSSH). No packets are sent to the remote.

Authentication

• SSH login — tries key/agent/existing-master auth first via a BatchMode=yes probe. If that succeeds, no login password is needed. If it fails, a masked overlay (● per character) collects the login password, fed to sshpass -e through the child's SSHPASS env var — never as an argv (no ps leak), never written to disk.
• Remote sudo (sudo: true) — when the SSH connection is passwordless, ssh_run first probes sudo -n true; if the remote sudoers is NOPASSWD the overlay shows a plain Allow/Deny with no sudo prompt. Otherwise a separate masked prompt collects the remote sudo password, piped to the remote sudo -S -p '' on stdin, so it travels inside the encrypted SSH channel, not as an argv.

Both passwords are cached in-memory per host for the session (keyed by user@host:port), never persisted. A wrong login password drops the login cache; a wrong sudo password drops the sudo cache — the next call re-prompts.

Connection reuse

OpenSSH ControlMaster multiplexing keeps one authenticated connection per host alive for a short ControlPersist window, so repeat ssh_run calls to the same host skip re-auth. Host-key policy is accept-new and ConnectTimeout is 10s.

While the approval dialog is open, ssh_run holds the shared agent-state coordinator in blocked (via withAgentBlock from @xynogen/pix-runtime), so an away user in a herdr pane is pinged when a command is waiting on approval. /afk (pix-commands) denies ssh_run immediately; /yolo auto-approves it only when no password is missing (a password prompt can't be auto-typed).

Completed calls collapse after the configured Pix delay into a status row such as ✓ ssh [email protected] apt update · exit 0 · 12 lines. Configure the delay with collapse.delaySec and the per-tool toggle with collapse.tools.ssh in ~/.pi/agent/pix.json. Overlays are never collapsed, and passwords are never included in result metadata or render state.

Requirements

• ssh (OpenSSH) on the local machine.
• sshpass on the local machine — only needed for password-based SSH login. Key-based auth works without it.

Install

pi install npm:@xynogen/pix-ssh

Standalone and opt-in. @xynogen/pix-core does not bundle it. Remote execution over SSH is a networked, privileged capability.

Full distro

This package is part of Pix. The installer sets up Pi and the full distro. See Install for the notes for each OS.

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.sh | sh

# Windows
irm https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.ps1 | iex

License

MIT. See LICENSE.