pi-zenmux-oauth

Use ZenMux models in Pi with OAuth 2.0 Authorization Code + PKCE. The extension registers the zenmux provider, discovers the current model catalog, and refreshes OAuth tokens with rotation.

Model requests prefer Anthropic Messages, then OpenAI Responses, and use Chat Completions only as a compatibility fallback. Protocol selection is performed per model from the endpoint adapters advertised by the ZenMux model catalog; the local fallback model uses Anthropic Messages when discovery is unavailable.

Compatibility

Plugin major versions follow Pi major versions. Version 1.x requires Pi 1.3.0 or a compatible newer Pi 1.x release, and Node.js 22.19 or later. It uses the current host-provided @earendil-works/pi-ai transports through Pi's supported extension entrypoint, with a * peer dependency and development tests pinned to Pi 1.3.0. Users of Pi 0.73 should remain on plugin 0.2.6.

Add and update the plugin

Install the package with Pi:

pi install npm:@zenmux/pi-zenmux-oauth

If it is already installed, update only this plugin:

pi update npm:@zenmux/pi-zenmux-oauth

To update all installed Pi extensions instead:

pi update --extensions

After updating, restart Pi so it reloads the new extension version. Check the installed package with:

pi list

Sign in and use

Start Pi and sign in:

/login zenmux

Pi opens the ZenMux authorization page in your browser. After approval, the browser redirects to a temporary loopback listener on 127.0.0.1, which renders https://zenmux.ai/platform/oauth-completed?client=pi in a full-screen iframe. Return to Pi, run /model, and select a ZenMux model.

How authentication works

• The official https://zenmux.ai service uses one bundled native public OAuth client ID.
• Authorization uses PKCE with S256; no client secret is stored or distributed.
• Existing client IDs are still read from ~/.pi/zenmux-oauth-clients.json to keep previously issued credentials working. Non-production origins register and cache a client on first use.
• Access and refresh tokens are managed by Pi's provider credential store.
• Refresh tokens rotate on every refresh.
• Model requests use the OAuth access token as a Bearer token. ZenMux API keys are not exposed to the extension.
• The extension loads and registers the model catalog during startup and retains it through Pi 1.x cache-only refreshes. It caches the catalog in zenmux-models.json under PI_CODING_AGENT_DIR (default ~/.pi/agent), supports offline startup, and keeps the last valid catalog when discovery fails or returns empty.
• Cached models are scoped to the configured OAuth origin and model catalog URL, so production and development catalogs are not mixed.

The package requests only these scopes:

• inference:invoke
• offline_access

Configuration

Production works without additional configuration. These environment variables are available for development and self-hosted testing:

Variable	Default	Purpose
ZENMUX_OAUTH_ORIGIN	https://zenmux.ai	OAuth authorization server origin
ZENMUX_API_BASE_URL	https://zenmux.ai/api/v1	OpenAI-compatible API base URL
ZENMUX_ANTHROPIC_BASE_URL	derived as https://zenmux.ai/api/anthropic	Anthropic-compatible API base URL
ZENMUX_MODEL_CATALOG_URL	https://zenmux.ai/api/frontend/model/available/list	Rich model catalog containing endpoint protocol adapters
ZENMUX_TEST_MODEL	deepseek/deepseek-v4-flash	Fallback model when discovery is unavailable
ZENMUX_OAUTH_CLIENT_ID	bundled for https://zenmux.ai	Override the public client ID for development or self-hosted environments

Local development

Load the extension directly:

pi -e ./index.mjs

Run against the ZenMux pre-release OAuth environment:

npm run dev

Validate the source and inspect the npm tarball before publishing:

npm test
npm pack --dry-run

Security

Pi packages execute with the permissions of the Pi process. Review package source before installation. This extension listens only on an ephemeral 127.0.0.1 port during OAuth authorization and verifies the returned OAuth state before exchanging the authorization code.

License

MIT