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 ssh_remote_control 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. Remote commands have a 30-second default timeout, oversized output is bounded before it reaches the model context, and full truncated output is preserved in a 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:

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

Return to local tools with:

/remote off

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 because they are stored in the local remote configuration.

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.

These requests are handled through the agent-facing ssh_remote_control tool; slash commands are optional.

Command reference

Command	Purpose
/remote ssh USER@HOST -p PORT	Save, select, and connect to an endpoint
/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 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
/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 the in-memory password

Persistence, output, and security

Endpoint configuration is stored locally in:

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

Saved values include endpoints, active endpoint, notes, remote working directories, forwards, and preview settings. Passwords are never written to this file: SSH agent authentication is preferred, and prompted passwords remain only in process memory.

New or changed host keys require interactive confirmation and are stored separately from OpenSSH. Remote output sent to the model is limited to 2,000 lines or 50 KB; oversized complete output is written to a temporary local file. Preview-line settings affect only the collapsed UI.

Current SSH scope

The extension currently supports direct SSH commands with -p and -l. It does not yet consume ~/.ssh/config, IdentityFile, or ProxyJump settings.

MIT licensed.