pi-ssh-remote

SSH designed for agents—not just for terminals.

中文文档 · Community

pi-ssh-remote turns a remote machine into Pi's active workspace. After connecting, the agent keeps using its normal read, write, edit, and bash tools, but those operations run on the remote server. There is no need to wrap every action in ssh ..., copy files back and forth, or make the model reason about two unrelated shells.

You: Connect to ssh root@gpu-box -p 2202, open /srv/training,
     find why the latest run failed, fix it, and restart it in the
     background. Return the PID and log path.

Pi:  connects → changes the persistent remote cwd → reads logs →
     edits remote files → launches the job on the GPU server

Designed for agent workflows

The remote machine becomes the agent's workspace

Once connected, Pi's file tools, shell tool, and ! user shell commands are transparently routed over SSH. The agent can inspect a repository, search logs, edit code, and run tests with the same tool interface it uses locally.

Agent control plane, human control plane

The extension exposes remote for the agent and /remote for the user. You can ask Pi to connect, inspect status, change directory, add a server note, execute a command, create a tunnel, or return to local work in natural language—and still take direct control whenever you want.

Stateful endpoints instead of disposable SSH commands

Each user@host:port endpoint remembers its remote working directory, note, and port-forward configuration locally. Notes such as H100 training, staging, or customer demo appear in configuration, status messages, and Pi's footer, so the active execution environment stays visible.

Resilient and bounded by default

Dropped connections are automatically re-established during the active session. SSH workspace state is also session-aware: /new inherits the current workspace, forks and clones retain their source workspace, and /resume restores the selected session's recorded endpoint, remote directory, routing mode, and forwards. Remote commands have a 30-second default timeout. Remote text reads fetch focused ranges instead of downloading complete files, command output is streamed through bounded buffers, and a 32 KB per-turn budget prevents parallel tools from flooding model context. Complete oversized command output is preserved in a permission-restricted temporary file.

Hybrid local/remote workflows

Tunnel mode forwards remote services to localhost while returning Pi's tools to the local machine. This is useful when the backend runs on a GPU server but the client, browser automation, or integration code lives locally.

Why not just run ssh in Bash?

Plain SSH command	pi-ssh-remote
Each tool call must wrap or reconstruct SSH	All agent file and shell tools route automatically
Working directory is easy to lose between calls	Remote cwd is persistent and visible
The model must track whether it is local or remote	Pi's prompt and footer identify the active workspace
Disconnects break the workflow	Active-session connections automatically reconnect
Tunneling and remote editing are separate setups	Workspace routing and port forwarding share one control plane
Large output can flood context	Preview and model-output limits are built in

Install

pi install npm:pi-ssh-remote

Requires Node.js 20+. The remote server must provide Bash, SFTP, and GNU timeout.

Quick start

/remote ssh root@gpu-box.example.com -p 2202
/remote cd /srv/project
/remote config note H100 training server
/remote status

From this point, normal Pi operations target /srv/project on the remote server. The footer makes that routing explicit:

H100 training server (root@gpu-box.example.com:2202):/srv/project

Return to local tools with:

/remote off

Server memory

Tell Pi what to remember for the current server:

Remember for this server: use /opt/conda/bin/python and never stop shared jobs.

List saved entries and their IDs:

/remote memory

Use an ID to update or delete an entry:

Update memory deploy-command to use /opt/deploy/v2/run.sh.
Delete memory obsolete-proxy-rule.

Pi automatically applies saved memory when you work on that server. Deletion only happens when you explicitly request it.

Private key authentication

Pass an explicit local private key with -i:

/remote ssh -i ~/.ssh/id_ed25519 root@gpu-box.example.com -p 2202

Identity paths must be absolute or start with ~/. Unencrypted and passphrase-protected private keys are supported. Pi prompts for an encrypted key's passphrase and caches it only in the current process for reconnects; /remote forget clears it. When -i is present, that key is used exclusively instead of silently falling back to SSH agent or password authentication. Commands without -i keep the existing SSH agent and password flow unchanged.

Examples

1. Let the agent investigate and repair a remote failure

Connect to ssh ubuntu@training.example.com -p 22 and work in /opt/app.
Inspect the failed deployment, trace the error through the logs and source,
make the smallest safe fix, run the relevant tests, and show me the diff.

The connection is established once. Subsequent reads, searches, edits, and tests are ordinary Pi tool calls routed to the server.

2. Launch a long GPU job without blocking the agent

On the current remote server, validate the training command first. Then launch
it with nohup in the background, redirect stdout and stderr from process start,
and report the PID, output directory, and log path. Verify that the process is
still alive and that the log has started.

The default foreground timeout prevents an accidental long-running command from occupying the agent indefinitely, while an explicitly backgrounded job continues on the server.

3. Keep several machines understandable

/remote ssh root@10.0.0.21 -p 22
/remote config note 8xH100 training
/remote config cwd /srv/train

/remote ssh ubuntu@staging.example.com -p 2222
/remote config note staging API
/remote config cwd /opt/service

/remote config
/remote use root@10.0.0.21:22
/remote

Endpoint notes and working directories survive Pi restarts and remain separate for each saved endpoint.

4. Expose a remote service while editing locally

/remote config forward 7860:127.0.0.1:7860
/remote forward

Now localhost:7860 reaches the service on the SSH server, while Pi's file and shell tools remain local. This is ideal for a remote model server paired with a local UI or client repository.

Stop the tunnels with:

/remote unforward

5. Ask Pi directly

Connect to my configured remote, switch to /srv/api, and inspect its Git status.

Add the note "production read-only" to this endpoint and tell me which remote
workspace is active.

Forward the remote service on port 8000 to localhost:8000, but keep my coding
tools on the local repository.

Command reference

Command	Purpose
/remote ssh USER@HOST -p PORT [-i KEY]	Save, select, and connect using agent/password or an explicit private key
/remote	Connect to the selected endpoint or prompt for one
/remote config	List saved endpoints and settings
/remote use USER@HOST:PORT	Select a saved endpoint
/remote config note TEXT	Persist a note for the selected endpoint
/remote config note --clear	Clear its note
/remote memory	List the current server's memory entries and IDs
/remote config cwd PATH	Persist its default remote working directory
/remote cd PATH	Change the connected remote cwd and persist it
/remote config forward MAPPING...	Persist port forwards such as 7860:127.0.0.1:7860
/remote forward [MAPPING...]	Start tunnels and keep Pi's tools local
/remote unforward	Stop extension-managed tunnels
/remote exec COMMAND	Run one command in the remote cwd
/remote exec --timeout 60 COMMAND	Override the command timeout
/remote exec --lines 20 COMMAND	Override collapsed preview lines
/remote config display-lines 10	Set default collapsed preview lines (maximum 50)
/remote config read-max-lines 400	Set the remote read line budget
/remote config read-max-bytes 16384	Set the remote read byte budget
/remote config exec-max-lines 200	Set the remote command line budget
/remote config exec-max-bytes 8192	Set the remote command byte budget
/remote config turn-max-bytes 32768	Set the aggregate per-turn remote output budget
/remote status	Show the active workspace
/remote reload	Reconnect the active workspace
/remote off	Disconnect and return tools to local execution
/remote forget	Disconnect and clear cached passwords and key passphrases

Persistence, output, and security

Endpoint configuration is stored locally in:

~/.pi/agent/ssh-remote-config.json

Saved global values include endpoints, active endpoint, notes, remote working directories, forwards, identity file paths, preview settings, and model-output budgets. Each Pi session also stores non-secret SSH workspace metadata so /resume can restore the server associated with that session. Private key contents, passwords, and key passphrases are never written to this file. Private keys are read locally only when connecting; prompted passwords and passphrases remain only in process memory.

New or changed host keys require interactive confirmation and are stored separately from OpenSSH. By default, remote text reads return at most 400 lines or 16 KB, remote command results return the last 200 lines or 8 KB, and all remote tools in one agent turn share a 32 KB output budget. Text reads support offset/limit continuation without downloading the complete remote file. Oversized command output is streamed to a permission-restricted temporary local file rather than accumulated in memory. Configured limits may be raised only to the extension's hard safety ceilings. Preview-line settings affect only the collapsed UI and never increase model output.

Current SSH scope

The extension currently supports direct SSH commands with -p, -l, and -i. It does not yet consume ~/.ssh/config or ProxyJump settings; use -i explicitly instead of relying on an IdentityFile entry.

Releases

Latest release: v0.1.12

Version	Date	Highlights
0.1.12	2026-08-25	Safe handling of repeated SSH errors when a connection is lost during handshake
0.1.11	2026-08-16	JSON memory entries, prompt-guided CRUD, and /remote memory listing
0.1.10	2026-08-16	Safe inspect-by-default and append-only agent updates for server memory

See CHANGELOG.md for the complete release history, including additions, behavior changes, and bug fixes.

MIT licensed.