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. Server memory is a per-user@host JSON file containing stable { "id", "content" } entries, so another SSH port for the same user and host uses the same entries. Pi is told the exact local file path and can use its normal read, edit, and write tools for entry-level CRUD even while other tools are routed remotely. 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. Valid server-memory entries are automatically injected into the model context whenever a matching endpoint is connected as the active remote workspace.

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

You: Add a server-memory entry saying to use /opt/conda/bin/python and never stop shared jobs.

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

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 in the local remote configuration. user@host-specific memory survives in a separate local JSON file under ~/.pi/agent/ssh-remote-memories/; each entry has a stable id and content. When Pi connects to an endpoint, valid entries matching its user and host are added to the model context on every agent run while remote tool routing remains active; the SSH port does not affect memory selection. Disconnecting or switching to tunnel-only mode removes them from subsequent model requests.

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.

Add a server-memory entry that says deployments must use /opt/deploy/run.sh.

List the current server's entries and IDs before referring to one:

/remote memory

Then update or delete by the displayed ID:

Update the entry with ID deploy-command to use /opt/deploy/v2/run.sh.
Delete the server-memory entry with ID obsolete-proxy-rule.

These requests are handled through the agent-facing remote tool; slash commands are optional. The memory action locates and inspects the matching JSON file, while Pi's normal read, edit, and write tools perform entry-level add, query, update, and delete operations. The injected instructions make deletion deliberately strict: Pi must first read the file, identify the exact entry ID, and delete only that object—and only after the user explicitly asks to delete, remove, or forget memory. Ambiguous targets require clarification, update requests do not imply deletion, and deleting all entries requires an explicit request to delete all server memory.

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, IDs, and JSON file path
/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. Server-memory entries are stored separately under ~/.pi/agent/ssh-remote-memories/ as { "server", "entries": [{ "id", "content" }] }; legacy string memories are migrated automatically. Each Pi session also stores non-secret SSH workspace metadata so /resume can restore the server associated with that session. Server memory is user-configured trusted context and is inserted into each model request only while a matching endpoint is the active remote workspace; it is not read from the remote server. The current server's exact memory path is the only local path that the routed read, edit, and write tools special-case. Private key contents, passwords, and key passphrases are never written to these files. 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.11

Version	Date	Highlights
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
0.1.9	2026-08-12	Stable deduplicated server-memory context and shorter footer labels

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

MIT licensed.