pi-gproxy

English | 简体中文

Sign in to Pi with your GPROXY account, discover the models you can access, and use different upstream providers through one gateway.

This is a standalone GPROXY provider. It does not modify Pi, replace Codex, or ask for your upstream provider credentials.

Requirements

• Node.js 22.19.0 or newer.
• Pi 0.85.1, the tested compatibility baseline. Package peer dependencies accept >=0.85.1 <0.86.0; other versions are not verified.
• A GPROXY v3 instance with unified account OAuth, such as v3 staging, and a GPROXY user account with access to at least one model.

Install and sign in

1. In GPROXY Console → Settings → OAuth clients, enable the preconfigured pi-gproxy client. Keep the redirect URL http://127.0.0.1/oauth/callback without a port: browser login allocates a local port automatically.

2. Install the extension:

   pi install npm:pi-gproxy

   To pin the first release, use pi install npm:pi-gproxy@0.1.0.

3. Start Pi, run /login, and select GPROXY.

4. Enter your instance origin, for example https://gproxy.example.com. Use HTTPS, or HTTP on loopback for local testing, such as http://127.0.0.1:8787. Subpaths, URL credentials, queries and fragments are not accepted.

5. Choose Browser on your own machine, or Device code for SSH, containers and approval from another device. Sign in to the GPROXY Portal and approve the request. Only approve a login you initiated.

6. Run /model and select a GPROXY model.

The login authorizes your GPROXY account, not an upstream account. Your administrator's current model permissions still apply.

Commands

Command	Purpose
/login → GPROXY	Sign in through browser PKCE or device authorization.
/gproxy-refresh	Force a refresh of models available to this account.
/fast [on|off]	Toggle priority service for a selected GPROXY model that advertises it.
/logout	Remove Pi's local credentials; this does not revoke the server session.

/fast is scoped to the model and authorization and lasts only for the current Pi process. Models without the advertised priority tier are not modified. Inference uses Pi's standard Responses streaming implementation at /v1/responses; WebSocket transport is not required.

Credentials, sessions and billing

• Pi stores the OAuth credentials and serializes token refresh. The instance origin is bound to the credential; refresh only contacts that instance's /oauth/token. This extension does not maintain another credential file or fall back to OpenAI.
• Model discovery uses /v1/models. Pi's model store caches the catalog per instance and authorization, including restoration after a restart. Normal refreshes use a 60-second cache window; /gproxy-refresh forces a new request.
• Rejected refresh or model authentication stops use of that authorization and prompts you to sign in again.
• To revoke access on the server, open GPROXY Portal → Authorized sessions and revoke the session. Pi's built-in /logout only removes local credentials.
• Cancelling device login makes a best-effort request to cancel the pending server flow. Browser cancellation closes the local callback listener. An authorization that never exchanges a code for tokens is not counted as a login.
• Pi's zero-cost placeholder does not mean free usage and is not your GPROXY bill. Actual usage and charges are recorded by GPROXY. This extension does not substitute prices from external model catalogs.
• Context limits, output limits, image input and thinking levels come from model discovery. When limits are missing, Pi's required fields use conservative defaults of 8192 context tokens and 4096 output tokens. Ask the administrator to complete the model metadata.

Troubleshooting

• Invalid or disabled client: enable pi-gproxy in Console and check the registered callback URL.
• No GPROXY models: run /gproxy-refresh and check your account's model permissions. Complete login normally rather than copying only an auth file: Pi also needs the discovered model catalog.
• Expired or revoked authorization: run /login again. Re-enabling a client does not restore previously revoked sessions.
• Cannot use a local browser callback: cancel and choose device-code login.

Development

git clone https://github.com/LeenHawk/pi-gproxy.git
cd pi-gproxy
npm ci
npm run check
npm pack --dry-run

Load the checkout with pi -e /absolute/path/to/pi-gproxy/src/index.ts, or install the local directory with pi install /absolute/path/to/pi-gproxy.

• src/auth/: browser PKCE, device authorization, refresh and cancellation.
• src/models.ts: explicit GPROXY model-to-Pi capability mapping.
• src/provider.ts: native Pi provider, OAuth, catalog cache and Responses streaming.
• src/index.ts: registration and the model-refresh/priority commands.

Tests use local simulated endpoints for state checks, PKCE, cancellation, serialized refresh and cache isolation. Local gateway integration also exercised OpenAI/Claude streaming, tool round trips and settlement with simulated upstreams. These checks do not establish production-provider compatibility.

License

MIT.