How I Made Pi Run on a Remote Machine Without Touching the Remote

#ai #pimono #productivity #devtools

I run pi on my laptop. My projects live on a remote Linux server.

That's a problem. pi reads files, runs git, discovers AGENTS.md and skills from your current directory. If your code isn't local, pi is blind.

The obvious fix is to sync files with rsync or mount the remote with SSHFS. Both work badly. Rsync adds a manual step before every session. SSHFS is flaky on macOS and kills git performance.

So I built pi-bridge.

What it does

pi-bridge makes pi think it's running locally , while everything actually happens on the remote.

You install one npm package. You add --ssh to your pi command. That's it.

pii --ssh user@host:/root/projects/my-app

Pi finds AGENTS.md. Pi finds your skills. Git branch shows in the footer. Pi has no idea it's not local.

How it works

The trick is intercepting pi before it touches anything.

pii (the binary) boots Node with a preload script that patches fs and child_process before pi's code ever runs. The patch redirects every filesystem call to a tiny HTTP server running on the remote over an SSH tunnel.

Local                              Remote
─────────────────────────────      ──────────────────────
pii (bin/pii.js)
  └─ node --require preload.js pi
       ├─ upload server to remote
       ├─ start HTTP server
       ├─ SSH port forward
       ├─ fake local dir in /tmp
       └─ patch fs.* + child_process.*   remote/index.js
                                          reads real files
pi loads — sees a local project           runs git commands
  fs.readFileSync(...)  ──GET──→          ← returns data
  spawn('git log')      ──SSH──→          ← runs on remote

Pi spawns git? That runs on the remote via SSH. Pi reads a file? That's an HTTP GET through the tunnel. Pi watches .git for branch changes? The bridge polls the remote every second.

Pi never knows.

The security model

The HTTP server only binds to 127.0.0.1 , nothing is exposed to the network. All traffic goes through the SSH tunnel. Every request requires a 32-byte random token generated at startup (never passed as a CLI arg, so it never shows in ps aux). The server rejects any path outside your project directory with a 403.

Why not just SSH into the machine and run pi there?

You could. But pi needs internet access for the Claude API and auth. A lot of remote machines, VMs, private servers, air-gapped boxes — don't have that. pi-bridge keeps all the internet-dependent parts local, while the code stays where it lives.

Install

npm install -g pi-bridge

Then use pii exactly like pi. Same flags, same everything, just add --ssh.

The repo is at github.com/zeflq/pi-bridge. Issues and PRs welcome.

DEV Community