pi-runat

Run a one-off agent task on a remote host over SSH.

What this is

When doing one-off tasks, like with pi -p '...', it's sometimes helpful to run the whole task against a remote machine: commands execute there, files are read and written there, and searches happen there. pi-runat makes this a single flag:

pi --runat server:/srv/app -p 'Refactor the config loader'

The --runat flag takes [user@]host[:path/to/directory]:

• --runat server — run on server, starting from the remote user's home directory
• --runat bob@server — run on server as bob
• --runat server:/srv/app — run on server, starting from /srv/app
• --runat bob@server:/srv/app — all of the above

There's no sandboxing and no connection multiplexing: every tool call is a plain ssh <target> "command". This just controls where the commands run and from what directory they start.

Features

• --runat '[user@]host[:path/to/directory]'

  Routes all standard tools (bash, read, write, edit, grep, find, ls) over SSH to the target host. Relative file paths resolve under the remote working directory; absolute paths are used as-is.

• Startup connectivity check

  On load, pi-runat verifies the target is reachable (ssh <target> "pwd") and resolves the remote home directory. An unreachable host or failed authentication aborts startup with a clear error.

• Automatic rg / fd install

  If the remote host lacks rg (for grep) or fd (for find), pi-runat downloads the static binary from GitHub releases and installs it to ~/.local/bin on the remote host. Installed binaries persist across sessions.

• Consistent user bash

  !command in the TUI runs on the remote host too.

How it works

Each standard tool is registered with SSH-backed operations:

• bash runs ssh <target> "cd <remote-dir> && command".
• read / write / edit transfer file contents over SSH (cat / cat >).
• ls / find / grep list, search, and match on the remote host.
• Paths given relative to the working directory map to the same relative path under the remote working directory; absolute paths pass through unchanged.

Install

Install the published npm package with Pi:

pi install npm:pi-runat

Pin a specific version when you want reproducible installs:

pi install npm:pi-runat@0.1.0

Install into the current project instead of your user Pi settings:

pi install npm:pi-runat -l

Or install from GitHub:

pi install git:github.com/player1537/pi-runat

Try it without permanently installing:

pi -e npm:pi-runat --runat server -p 'What is the hostname?'

Quick start

Try this package locally (replace server with a host you can SSH to):

pi -e . --runat server -p 'What is the hostname?'

Expected output:

server

Package contents

Development

npm install
npm run ci

npm run ci runs typecheck, unit tests, the Pi-host smoke harness, and a pack check.

Security

Pi packages can execute code with your local permissions. Review extensions before installing third-party packages.

pi-runat runs commands on the remote host with the permissions of the SSH user. It performs no sandboxing by design — only route execution with --runat. Use key-based authentication so the startup check and tool calls do not prompt for passwords.

For vulnerability reporting, see SECURITY.md.

Links

• npm: https://www.npmjs.com/package/pi-runat
• GitHub: https://github.com/player1537/pi-runat
• Issues: https://github.com/player1537/pi-runat/issues

License

MIT