System Tray App

The BitDrip tray app is a lightweight Electron application that manages the proxy daemon on end-user workstations. It runs in the system tray on macOS, Windows, and Linux and provides one-click start/stop, status visibility, diagnostics, and admin-managed update status.

In this section:

• System Tray App — installation, menu, status indicator, auto-update
• CA Certificate Management — CA lifecycle, rotation, audit log

Installation

Admin: inviting a user

From the dashboard, go to Settings → Workstations and click Invite User. Enter the employee's email address. They will receive an email with:

1. Per-platform download buttons (Linux, macOS, Windows)
2. A one-click Enroll this computer button (see One-click enrollment below)
3. A fallback terminal command for manual enrollment

The enrollment token in the invite is single-use and expires in 24 hours.

One-click enrollment

After installing the tray app, the invited user clicks Enroll this computer in the email. This opens a bitdrip://enroll deep link that the tray app handles automatically:

1. The OS passes the link to the running tray app (or launches it if not running)
2. The tray app validates the server URL and token
3. bitdrip enroll runs silently in the background
4. A system notification confirms success: BitDrip Enrolled ✓

No terminal required. The workstation appears in the dashboard within seconds.

If the button doesn't open the app (OS hasn't registered the URI scheme yet — can happen before first launch), use the manual command shown in the fallback section of the email:

bitdrip enroll --server https://<your-policy-engine> --token <enrollment-token>

Platform downloads

The tray app is also available directly at https://releases.bitdrip.app/v<VERSION>/tray/:

Platform	File	Command
Linux Debian/Ubuntu	.deb	sudo apt install ./BitDrip-<version>-Debian-amd64.deb
Linux RHEL/Fedora	.rpm	sudo dnf install ./BitDrip-<version>-RPM-x86_64.rpm
Experimental AppImage	.AppImage	Evaluation only; prefer .deb or .rpm for managed deployment
macOS	macos.dmg	Open and drag to Applications
Windows	windows.exe	Run installer (no admin required)

Platform notes

Platform	Format	Notes
macOS	DMG; notarized when signed channel is available	Installs to /Applications/BitDrip.app; added to Login Items
Windows	NSIS installer; code-signed when signed channel is available	Installs to %APPDATA%\BitDrip; added to Startup
Linux	.deb or .rpm	Installs desktop entry, URI handler, CLI helper, and systemd user unit
Linux experimental	AppImage	Manual evaluation only; no package-managed autostart, URI handler, dependencies, certificate trust, or uninstall cleanup

Tray Menu

Right-click the tray icon to access:

• Start Proxy / Stop Proxy — toggle the MITM proxy daemon
• Enable Routing / Disable Routing — activate or deactivate the PAC file without stopping the daemon
• Open Dashboard — opens the Admin Dashboard in the default browser
• Update Available — appears when a newer version is detected; opens the dashboard for administrator-managed update guidance
• Certificate Status — shows CA validity and remaining days (⚠ warning when ≤ 30 days remain)
• Status — current proxy state, uptime, and request counts

Status Indicator

Icon	Meaning
Green	Proxy running, routing active
Yellow	Proxy running, routing disabled — or CA certificate expiring soon
Red	Proxy stopped
Gray	Daemon unreachable

When the CA certificate is within 30 days of expiry, the tray tooltip changes to "BitDrip — CA certificate expiring soon" and the Certificate Status menu item shows the exact days remaining. Run bitdrip cert renew to regenerate and re-install the CA before it expires.

Update Status

The tray app checks the client update metadata endpoint for new versions on startup and periodically while running. Updates are admin-managed: the tray reports status but does not download, execute, or elevate an installer.

When a newer version is available:

1. A native OS notification reports that a newer version is available.
2. The tray menu shows Update Available.
3. The only action opens the dashboard for administrator-managed update guidance.
4. The operating system, package manager, MDM, or enterprise deployment tool performs the actual install.

The update check requires only outbound HTTPS to the configured client metadata endpoint.

Proxy Daemon Control

The tray app manages the proxy daemon process directly. It is equivalent to running these CLI commands:

bitdrip proxy start    # Start Proxy
bitdrip proxy stop     # Stop Proxy
bitdrip proxy enable   # Enable Routing
bitdrip proxy disable  # Disable Routing
bitdrip proxy status   # View status

Configuration

The tray app reads its configuration from the file written during enrollment:

~/.bitdrip/config.json

This file contains the policy engine URL, workstation ID, and API key. It is written automatically during enrollment and should not be edited manually.

Troubleshooting

Tray icon does not appear
On Linux, ensure your desktop environment supports system tray icons (libappindicator or libayatana-appindicator3).

"Policy engine unreachable" shown in status
The proxy daemon cannot reach the policy engine configured in ~/.bitdrip/config.json. Check network connectivity and that the policy engine is running. The daemon continues to operate using the local policy cache.

Proxy not intercepting traffic after enabling routing
Run bitdrip diagnose in a terminal to check CA cert trust, PAC file accessibility, and proxy daemon health.

"Enroll this computer" button does nothing
The bitdrip:// URI scheme is registered by the installer. If the button does nothing:

1. Confirm the tray app is installed and has been launched at least once (first launch registers the URI scheme on Windows and Linux)
2. On macOS, check System Settings → General → Login Items — BitDrip should be listed
3. Use the manual command from the fallback section of the invitation email

"BitDrip — Enrollment Failed" notification
Common causes: the enrollment token has expired (24-hour limit), the token was already used, or the policy engine server URL in the invite is not reachable from this workstation. Ask your admin to send a new invitation.

See Troubleshooting for more.