English | 简体中文
Pi Web Tray is a Windows 7 to 11 Harness solution based on Pi Web. It provides runtime detection, dependency installation and updates, service hosting and self-update.
- One click — installs and manages Pi Web; start or stop the service with one click.
- Visible state — color-coded tray icon, notifications and live logs.
- Start at login — uses the standard Run key or an administrator scheduled task.
- Port safe — native process APIs identify the listener; unrelated programs are never killed.
- Self-update — checks for updates, updates the app and removes files from older releases.
- Portable — no installer and no bundled runtime.
| Component | Requirement |
|---|---|
| 64-bit Windows | 7 SP1, 8.1, 10 or 11 |
| .NET Framework Runtime | 4.8 — required; 4.8.1 is also supported on Windows 10 20H2+ and 11 |
| Node.js | 22.19 or later, with npm |
Windows 7 has no official Node.js 22 build. Download Node.js asks for confirmation and then opens an unsigned community build; it is not produced or verified by this project. Pi Web's terminal needs ConPTY (Windows 10 1809+), so Pi Web can run on legacy systems, but terminal functionality may be impaired.
Windows 7 SP1 and Windows 8.1 need .NET Framework 4.8 rather than 4.8.1. If checking for updates on Windows 7 cannot reach GitHub, install the TLS 1.2 update.
- Download and extract the release archive.
- Run
.\pi-web-tray.exe.
On first start Pi Web Tray checks the environment, installs missing dependencies, starts Pi Web and opens the browser. With the default AutoInstall=1, missing dependencies are installed automatically during a normal start. If Node.js is missing, it explains the required version and offers the download page; Pi Web Tray stays running and rechecks when Node.js appears. When Node.js was installed after that prompt, automatic installation stays off: missing dependencies are reported and the menu offers Install/update service. If Node.js is removed while Pi Web is running, Pi Web Tray notifies you without stopping the running service and rechecks before the next start. If an install is interrupted, the next attempt reinstalls the relevant packages instead of trusting an incomplete directory.
Configuration and logs live in %LOCALAPPDATA%\pi-web-tray by default. Set PI_WEB_TRAY_PORTABLE=1 to keep the ini and logs beside the executable. Portable mode is ignored when the executable is in a protected system directory such as C:\Program Files. Even in portable mode, state.ini (the legacy state file), the per-session state.<session>.ini, crash.log and update work files remain in the data directory. The pi-web-tray.files.txt manifest is used by future updates to remove files that are no longer shipped; do not delete it.
The icon colour shows the state at a glance:
| Colour | State |
|---|---|
| 🟢 Green | Running |
| ⚪ Grey | Stopped |
| 🟠 Orange | Busy: checking, installing, starting/stopping the service, or applying an update |
| 🔵 Blue | Missing prerequisites (Node.js / Pi Web) |
| 🔴 Red | Error or port conflict |
The menu follows the service state:
● Running · 127.0.0.1:30141 · administrator mode
---------------------------------------
Open browser
Start service
Stop service
Restart service
---------------------------------------
Update service
Download Node.js
---------------------------------------
Environment check
Settings...
Logs >
View service runtime log
View service install/update log
View software update log
Open data folder
Open program folder
Open configuration file
Copy page link
Create desktop shortcut
---------------------------------------
Start at login: Enabled (standard user)
Start at login as administrator: no
---------------------------------------
Restart as administrator
Check for updates
About
Exit and stop service
- Update service stops Pi Web first, reinstalls or updates Pi Web (and Pi when
InstallPi=1), and restarts it automatically only if the service was running before the update. When dependencies are missing, the same item is shown as Install/update service. The progress window supports cancellation; while the self-update helper is replacing files, the tray exit action is disabled. - A listener is treated as Pi Web Tray's service only when it belongs to the same Windows session and runs the installed
pi-web.js. Another session or installation is a port conflict, so Pi Web Tray neither opens nor stops it. ChangePortin Settings if needed. - If Pi Web stops unexpectedly, Pi Web Tray reports it. With
AutoRestart=1it restarts automatically for up to three consecutive rapid failures (5/15/30 s delays); a service that stays up for 60 s resets the retry counter. WithAutoCheckUpdates=1it checks for a new release after startup.
pi-web-tray.ini lives in %LOCALAPPDATA%\pi-web-tray by default, so separate Windows users do not share settings. Set PI_WEB_TRAY_PORTABLE=1 to keep the ini and logs next to the executable (ignored for protected system directories). A commented sample is in config/pi-web-tray.ini.
| Key | Default | Description |
|---|---|---|
Port |
30141 |
Pi Web listening port. |
WorkingDir |
%USERPROFILE% |
Service working directory. |
AutoInstall |
1 |
Install missing dependencies at startup. |
InstallPi |
1 |
Also install/update Pi with Pi Web; set 0 to skip. |
AutoRestart |
0 |
Restart Pi Web after an unexpected stop. |
AutoCheckUpdates |
0 |
Check for a Pi Web Tray update after startup. |
InstallTag |
latest |
Pi Web npm distribution tag or exact version. |
NpmRegistry |
empty | Custom registry, e.g. https://registry.npmmirror.com. |
Proxy |
empty | Optional HTTP or SOCKS5 proxy for update checks/downloads; empty uses the system proxy. |
NodePath |
empty | Explicit node.exe; empty enables auto-detection. |
Language |
auto |
auto, en, zh (Simplified) or zh-Hant. |
AutostartAdmin |
0 |
Admin rights for start at login (menu-managed). |
Values support %ENV% expansion. Quote values containing ; or #; comments need whitespace before the marker. Relative WorkingDir and NodePath values are resolved against the executable directory.
When the Pi Web Tray installation directory, any folder in its path, or any file the elevated process loads can be modified or renamed by standard users, enabling administrator start-at-login is refused without changing the current setting. The security warning offers a Fix button that repairs the folder ACL through UAC when the rest of the path is protected. For a portable or user-profile installation, the Fix action reports that the program must be moved to a protected location such as Program Files; a user-writable parent cannot be repaired safely. If the administrator preference is unavailable and the user enables start-at-login from the main menu, Pi Web Tray clears that preference and uses standard-user start-at-login instead.
The data directory is per user. Pi Web Tray redacts URL user info and token query values from its logs. When Proxy is set, only Pi Web Tray update checks and downloads use it. An empty value uses the system proxy. The setting is not passed to Node, npm or Pi Web child processes. The Test button in Settings only tests proxy connectivity and does not save.
| Variable | Description |
|---|---|
PI_WEB_TRAY_INSTANCE |
Isolated instance: separate mutex, signals, config, data and start-at-login entries. With PI_WEB_TRAY_HOME, data goes under HOME\pi-web-tray.<name>. |
PI_WEB_TRAY_PORT |
Overrides the configured port. |
PI_WEB_TRAY_LANG |
Overrides the UI language. |
PI_WEB_TRAY_HOME |
Overrides the data directory root and takes precedence over portable mode. |
PI_WEB_TRAY_PORTABLE |
1 keeps the ini and logs beside the executable. |
PI_WEB_TRAY_NO_NODE |
Test hook: simulate a missing Node.js installation. |
PI_WEB_TRAY_NO_PIWEB |
Test hook: simulate a missing Pi Web package. |
PI_WEB_TRAY_NO_PICLI |
Test hook: simulate a missing Pi package. |
Named instances use separate names for their legacy start-at-login entries, but start-at-login cannot be enabled for a named instance; use the default instance for start-at-login. A Run value or scheduled task does not preserve the launching environment.
.\pi-web-tray.exe Start the service and open the browser.
.\pi-web-tray.exe --autostart Start Pi Web Tray and the service without opening a browser.
.\pi-web-tray.exe --tray-only Start Pi Web Tray only, without the service.
.\pi-web-tray.exe --start-no-open Start the service without a browser.
.\pi-web-tray.exe --stop Stop the service; keep Pi Web Tray running if it is present.
.\pi-web-tray.exe --quit Stop the service and exit.
.\pi-web-tray.exe --check Check the environment (0 = ready, 1 = missing).
.\pi-web-tray.exe --install Install dependencies without starting Pi Web Tray.
.\pi-web-tray.exe --dry-run With --install, print the npm commands without installing.
.\pi-web-tray.exe --diag Write a diagnostic snapshot to diag.txt.
.\pi-web-tray.exe --lang-check Verify that every UI string is complete for all supported languages.
.\pi-web-tray.exe --make-ico Generate the application icon (build tool).
.\pi-web-tray.exe --version Print the version.
.\pi-web-tray.exe --help Show command-line help.
Unknown arguments return exit code 2.
--install stops a running service before npm runs and restarts it only when a tray is running. Without a tray the service remains stopped. If the tray is elevated, run --install from an elevated console as well.
Choose one build tool:
- .NET SDK 8.0 or later (recommended for command-line builds), or
- Build Tools for Visual Studio 2022 (MSBuild only).
Either tool requires the .NET Framework 4.8 Targeting Pack. The standalone .NET Framework 4.8 Developer Pack includes it.
Visual Studio 2022 or later with the .NET desktop development workload is an optional IDE, not a separate requirement. The application targets .NET Framework 4.8, not .NET 8. End users only need the .NET Framework 4.8 Runtime (or 4.8.1 where supported).
git clone https://github.com/Arondight/pi-web-tray.git
cd .\pi-web-tray
.\build.cmd- Runs with the current user token (
asInvoker); elevation only on request. No telemetry; the tray itself opens no persistent listener (Pi Web listens on loopback). A SOCKS5 update proxy opens a process-scoped loopback listener that only the current tray process may use; it is closed when the proxy setting changes or the process exits. - Administrator mode requires the tray installation directory and every file the elevated process loads (executable,
.config, satellite resources) to be protected. Manual elevation, elevated dependency installs, and elevated self-updates are refused when the installation directory is writable by standard users. An elevated start from a user-writable installation is refused before the ini and satellite resources are loaded. This check does not protect user-writable configuration or user-installed Node/npm and Pi packages; admin mode still executes those with the elevated token. Do not enable it on a machine where the same account's non-elevated processes are untrusted. - Updates are downloaded from GitHub over HTTPS and verified against the published SHA-256. The verified archive is copied into a target snapshot, re-hashed against that published checksum, extracted there, and used for the file replacement; the user-writable staging tree is not trusted. The snapshot is protected when the installation directory is protected. Releases are unsigned, so SmartScreen may warn on first run; this checksum is not a substitute for code signing.
- Admin start-at-login requires the current Windows account to be a member of the Administrators group and creates an on-logon task for the current user. Standard-user over-the-shoulder UAC and manual elevation are refused. The eligibility check includes files the elevated tray loads, not only
pi-web-tray.exe. The task name includes the user SID and named-instance suffix, so another user's or instance's task is not overwritten. A legacyPiWebTraytask is reported. A task with the current user's principal is removed when autostart is next changed; a task without an explicit user or for another account is left untouched. server.log,install.logandupdate.logrotate at 4 MB. If the tray runs elevated, use an elevated console for--stop/--quit. The tray menu always works. If the log-host child cannot be created, service output falls back to the unredacted, non-rotating1>>path described in SECURITY.md; if the configured log path is a reparse point, service output is discarded instead of following it.- The administrator start-at-login task is scoped to the current Windows user and keeps running on battery power. It does not inherit the environment of the shell that enabled it.
Pi Web Tray installs and launches Pi Web; when InstallPi=1, it also installs or updates Pi. It does not bundle or modify either project; report their issues to their own repositories.
Read CONTRIBUTING.md and CODE_OF_CONDUCT.md. Report vulnerabilities according to SECURITY.md.