@0x1f/pi-smart-proxy

A small Pi extension that routes Undici traffic by target domain, IP address, or CIDR through direct connections, HTTP(S) proxies, or SOCKS5 proxies.

SOCKS5 target names are resolved by the proxy. Both socks5:// and the familiar socks5h:// spelling are accepted.

Structure

extensions/smart-proxy/index.ts  # Pi extension
examples/smart-proxy.json        # Safe example configuration
tests/smart-proxy.test.ts        # Focused tests
index.ts                          # Local auto-discovery compatibility loader

Install

Requires Node.js 22.19 or newer. Install the tagged Git repository:

pi install git:github.com/0x1f/pi-smart-proxy@v0.2.0

Configure

Create ~/.pi/smart-proxy.json from examples/smart-proxy.json, adjust the proxy addresses, and protect credentials if present:

chmod 600 ~/.pi/smart-proxy.json

{
  "default": "direct",
  "proxies": {
    "socks": "socks5h://127.0.0.1:7890",
    "http": "http://127.0.0.1:7890"
  },
  "rules": [
    {
      "via": "socks",
      "domains": [
        ".openai.com",
        ".chatgpt.com",
        ".x.ai",
        ".grok.com"
      ],
      "cidrs": [
        "192.0.2.0/24",
        "2001:db8::/32"
      ]
    }
  ]
}

Rules are checked in order, and each rule may contain domains, cidrs, or both:

• example.com matches only that host.
• *.example.com matches subdomains, but not the apex.
• .example.com matches the apex and all subdomains.
• 1.1.1.1 and 2001:db8::1 match exact IPv4 and IPv6 targets.
• 10.0.0.0/8 and 2001:db8::/32 match literal target IPs in those ranges.

CIDR rules never resolve hostnames locally, preserving SOCKS5 proxy-side DNS and avoiding DNS leaks.

Proxy URLs may use http:, https:, socks:, socks5:, or socks5h:. HTTP and SOCKS5 username/password authentication use standard URL credentials:

{
  "proxies": {
    "socks": "socks5h://username:password@127.0.0.1:7890",
    "http": "http://username:password@127.0.0.1:7890"
  }
}

Percent-encode reserved characters in credentials, such as @ as %40. /proxy-status always redacts credentials.

Restart Pi or run /reload, then use:

/proxy-edit
/proxy-status
/proxy-reload
/proxy-test api.x.ai

/proxy-edit opens the current JSON in Pi's multiline editor, validates it before an atomic 0600 save, and reloads it immediately. Canceling leaves the file unchanged.

Notes

• Successful startup is silent; the status line shows activity, while configuration failures still notify.
• Status and route-test results use the active Pi theme; HTTP 2xx is green, 3xx yellow, and 4xx/5xx red.
• The extension restores the previous global Undici dispatcher when Pi unloads it.
• An explicit proxy argument or global proxy setting in pi-web-access uses its curl transport and therefore bypasses this dispatcher.
• Undici currently marks Socks5ProxyAgent experimental.

Development

npm install
npm test
npm pack --dry-run

License

MIT