@heihei0299/pi-switch

Lightweight profile switcher for pi models.json

Packages

Package details

package

Install @heihei0299/pi-switch from npm and Pi will load the resources declared by the package manifest.

npm report
$ pi install npm:@heihei0299/pi-switch
Package
@heihei0299/pi-switch
Version
20261111.0.0
Published
Nov 11, 2026
Downloads
253/mo · 34/wk
Author
heihei0299
License
MIT
Types
package
Size
28.3 MB
Dependencies
0 dependencies · 0 peers

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-switch

Version Platform Built with Go License

A Native Desktop control plane for pi agent, with Linux CLI and TUI support.

Manage provider profiles and publish a local model-name gateway. The MyGo Native Desktop app is the only Desktop GUI; the CLI, TUI, management API, and headless Proxy remain available independently.

English | 中文

What it does

  • Manage provider profiles, model lists, and per-channel model exposure.
  • Preview and publish models to Pi through the Gateway page.
  • Route requests through a local proxy using the model name.
  • View request and token usage, and manage pi packages from Native Desktop.
  • Use the same Go core through Native Desktop, CLI, TUI, and the management API.

For architecture and management API details, see archive/docs/architecture.md, archive/docs/management-api.md, and archive/docs/system-contract.md.

Install

From npm

npm install -g @heihei0299/pi-switch

# Or install through pi
pi install npm:@heihei0299/pi-switch

Build from source

Requires Node.js 23.6 or later and Go 1.24.2 or later.

git clone https://github.com/heihei0299/pi-switch.git
cd pi-switch
npm run build
node bin/pi-switch.js webui start --daemon

New CLI/npm versions support Linux amd64 and arm64 only. macOS and Windows are unsupported; historical releases are unchanged. See releases for available downloads.

Quick start

Start the management API (the legacy webui command name remains; its browser UI is retired):

pi-switch webui start --daemon

The management API remains available under /api/*; / displays the WebUI retirement notice. This command does not open a browser UI, and Desktop always uses MyGo Native (--web is no longer supported). Run environment checks with pi-switch doctor and stop the API with pi-switch webui stop. The terminal interfaces are also available: pi-switch tui or other pi-switch commands.

Use a model in Pi

  1. Add a provider and expose its models in Profiles.
  2. In Gateway, review the proposed changes and select Apply to Pi.
  3. Start the proxy from Proxy, or run pi-switch proxy start --daemon.
  4. In Pi, select pi-switch-res for Responses models or pi-switch-chat for Chat models, then choose an exposed model.

Stopping a managed daemon verifies its process identity with a Linux pidfd. If pidfds are unavailable or blocked, stop fails closed instead of signaling a possibly reused PID.

The management API binds to loopback by default. Binding to a non-loopback address requires a password; see the management API security guide.

Common questions

How do I switch models in Pi?

Open /model, select the published pi-switch-res or pi-switch-chat provider, and choose an exposed model.

Where is data stored?

Configuration and local request data are stored under /.pi-switch/. Pi's provider registry is /.pi/agent/models.json.

Development

Requires Node.js 23.6 or later and Go 1.24.2 or later.

npm run build
npm test
bash scripts/functional-check.sh bin/pi-switch

Acknowledgments

License

MIT