Persistent SSH

Persistent SSH is a portable OpenSSH helper and reusable instruction set for working on remote machines without installing an agent server, VS Code server, MCP daemon, or any other target-side runtime.

It uses the user's local OpenSSH configuration and connection multiplexing to keep one authenticated SSH transport alive. Commands, shells, file transfers, forwarding, and protected remote text patches can reuse that connection. The remote side only needs its existing sshd; protected patch edits additionally use standard remote git and patch.

Why This Exists

Many AI coding tools work well on local projects but ask users to install an agent process on every remote machine they want to edit. That is not always possible or desirable:

• small devices and edge boxes may not have room for another runtime
• locked-down servers may not allow agent daemons
• production-like machines should not gain extra long-running services
• a user's existing SSH keys, config, bastions, and jump hosts already solve access

Persistent SSH keeps the trust boundary simple: the agent runs local shell commands, OpenSSH handles transport, and the target stays a normal SSH server.

What It Can Do

• list concrete hosts from ~/.ssh/config
• resolve effective OpenSSH config with ssh -G
• start or reuse one persistent ControlMaster connection
• run remote commands through that connection
• open interactive shells
• transfer files with scp or sftp
• add and cancel local, remote, or dynamic forwards
• pass through arbitrary native ssh flags
• apply remote text edits as minimal unified diffs with sidecar git snapshots and optional verification rollback
• fall back to direct SSH on native Windows clients where ControlMaster is unavailable

Quick Start

python scripts/persistent_ssh.py list
python scripts/persistent_ssh.py resolve my-host
python scripts/persistent_ssh.py connect my-host
python scripts/persistent_ssh.py exec my-host -- uname -a
python scripts/persistent_ssh.py shell my-host
python scripts/persistent_ssh.py status
python scripts/persistent_ssh.py close

Use python on Windows and python3 where that is the available executable.

Use From Any Shell-Capable Agent

The helper is agent-agnostic. Any tool that can run local shell commands can use it directly:

• Codex
• Claude Code
• GitHub Copilot CLI
• shell scripts
• CI jobs with SSH credentials available

A concise reusable agent instruction is available in references/agent-usage.md.

Optional Codex Skill

Codex can use this repository as a skill, but the helper itself is not Codex-specific. To install the Codex skill, clone this repository into your Codex skills directory:

git clone https://github.com/Arash-san/persistent-ssh.git ~/.codex/skills/persistent-ssh

On Windows PowerShell:

git clone https://github.com/Arash-san/persistent-ssh.git $env:USERPROFILE\.codex\skills\persistent-ssh

Then ask Codex to use the persistent-ssh skill when you need remote SSH work.

Protected Remote Edits

For normal code, config, and documentation changes, use patch instead of uploading a full replacement file:

python scripts/persistent_ssh.py patch my-host --cwd /root/project -- -p0 < change.diff

The helper:

1. snapshots the selected remote --cwd into a sidecar git repository
2. dry-runs the incoming unified diff
3. applies the patch only if the dry-run succeeds
4. creates a post-edit snapshot
5. runs git diff --check
6. prints a restore command

For high-risk edits, add a verification command and automatic rollback:

python scripts/persistent_ssh.py patch my-host --cwd /etc/nginx \
  --verify-cmd "nginx -t" --rollback-on-verify-fail -- -p0 < nginx.diff

Use scp, sftp, or rsync for generated assets, binary files, archives, and large transfers.

Port Forwarding

python scripts/persistent_ssh.py forward my-host -- -L 127.0.0.1:8080:127.0.0.1:80
python scripts/persistent_ssh.py cancel-forward my-host -- -L 127.0.0.1:8080:127.0.0.1:80

For native SSH behavior that is not wrapped directly:

python scripts/persistent_ssh.py ssh -- -J bastion my-host uname -a
python scripts/persistent_ssh.py args my-host

Requirements

• local Python 3.10+
• local OpenSSH client
• reachable target with normal sshd
• remote git and patch only when using protected remote patch edits

No Python package dependencies are required.

Repository Layout

SKILL.md                     Optional Codex skill instructions
scripts/persistent_ssh.py    OpenSSH helper CLI
references/agent-usage.md    Concise reusable agent instructions
agents/openai.yaml           Optional OpenAI/Codex-facing metadata
assets/header.png            README header art

Security Notes

• uses your existing SSH config, keys, agent, bastions, and known_hosts behavior
• does not copy private keys
• does not disable host key checking
• does not install or persist anything on the remote target except optional sidecar git snapshots for protected patches
• keeps local connection state under your user profile or runtime directory

License

MIT. See LICENSE.