Pi Security: Route the Coding Agent Through Pipelock

Pi is a terminal coding agent. It reads a global httpProxy setting from ~/.pi/agent/settings.json and turns it into the HTTP_PROXY and HTTPS_PROXY environment variables. Pipelock uses that setting: pipelock pi install points it at a dedicated listener, so Pi’s proxy-aware traffic routes through Pipelock under the pi agent profile. Of Pi’s own settings, the installer changes only that one. See Pi’s proxy setting documentation for the upstream side.

What this covers

This setup routes requests that honor the proxy setting through Pipelock. For HTTPS, Pipelock sees only the destination of a plain CONNECT tunnel; scanning headers and bodies needs TLS interception and a Pipelock CA that Pi trusts. Tools and subprocesses that ignore proxy environment variables need separate network containment. See the containment guide for that.

Pi’s default provider is Google Gemini. Set GEMINI_API_KEY, or store the key under google in Pi’s auth file. pipelock pi install doesn’t log Pi into Gemini.

Install pipelock

# Go
go install github.com/luckyPipewrench/pipelock/cmd/pipelock@latest

# Homebrew (macOS / Linux)
brew install luckyPipewrench/tap/pipelock

Add a named listener

A named listener is a proxy port that belongs to one agent profile. Requests arriving on this listener receive the Pi profile, so Pipelock doesn’t have to trust a self-declared header to tell agents apart. Restrict who can reach the listener if that profile must mean Pi alone. Named agent listeners require Pipelock Pro. Add one for Pi to your Pipelock config:

forward_proxy:
  enabled: true

agents:
  pi:
    listeners:
      - "127.0.0.1:18991"

Start or restart Pipelock with that config. Pipelock binds listener sockets at startup, so a listener change needs a restart.

Install

Preview the settings change first. The proxy URL must match the listener in the named profile.

pipelock pi install --config "$PWD/pipelock.yaml" --profile pi \
  --proxy http://127.0.0.1:18991 --dry-run

pipelock pi install --config "$PWD/pipelock.yaml" --profile pi \
  --proxy http://127.0.0.1:18991

--config is the Pipelock config that defines the listener, --profile names the agent profile, and --proxy is the HTTP URL of that listener. The command updates only the global httpProxy member and keeps Pi’s other settings. It uses PI_CODING_AGENT_DIR when set, so an overridden Pi config directory gets the change instead. On success it prints that it configured Pi in the settings path to use the profile and proxy, and reminds you to restart Pi after restarting Pipelock.

The command refuses when the config doesn’t define the named profile or when the profile has no listener matching the proxy URL.

Verify

The installer compares Pi’s settings with your config file. It can’t prove that Pipelock has an active Pro license or that the listener bound. So check both:

1. Confirm the Pi listener appears in Pipelock’s startup output.
2. Restart Pi and check that the httpProxy value in ~/.pi/agent/settings.json (or under PI_CODING_AGENT_DIR) is your listener URL.

A second install with the same values reports that Pi already routes through the proxy. An offline walkthrough that never touches your real settings lives in the pi-integration example. It uses PI_CODING_AGENT_DIR and needs no Gemini key.

Remove

The installer records Pi’s prior httpProxy value beside its settings. Remove restores that value and keeps changes made after installation:

pipelock pi remove --dry-run
pipelock pi remove

Restart Pi to apply it. Re-running install recovers a prepared install only when Pi’s proxy still matches the recorded target or prior value. The command refuses to overwrite a changed proxy value or an interrupted removal. Inspect the settings and the state file before resolving another interrupted condition by hand.

See also: Continue.dev MCP Security · Contain an AI Agent on Linux · Pipelock v3.6 Upgrade Guide · Pi integration guide