Skip to content

About

Pi Web Tray is a Windows 7 to 11 Harness solution based on Pi Web.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Pi Web Tray

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.

Runtime requirements

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.

Older Windows runtime

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.

Quick start

  1. Download and extract the release archive.
  2. 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.

Tray menu

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. Change Port in Settings if needed.
  • If Pi Web stops unexpectedly, Pi Web Tray reports it. With AutoRestart=1 it 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. With AutoCheckUpdates=1 it checks for a new release after startup.

Configuration

Configuration file

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.

Environment variables

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.

Command line

.\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.

Build from source

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

Security and limitations

  • 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 legacy PiWebTray task 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.log and update.log rotate 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-rotating 1>> 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.

Related projects

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.

Contributing

Read CONTRIBUTING.md and CODE_OF_CONDUCT.md. Report vulnerabilities according to SECURITY.md.

License

MIT

About

Pi Web Tray is a Windows 7 to 11 Harness solution based on Pi Web.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages