Skip to content

System tray icon

The tray icon is a small icon in the notification area of your desktop (Windows), the menu bar (macOS) or the system tray (Linux). It answers three questions at a glance: is Tegvia protecting me, did it just block something, and how do I reach the web console. It adds no window of its own. Launching the icon launches Tegvia: if the background service is installed but stopped, the icon starts it (once, with no retry). Quitting the icon stops Tegvia, after confirmation (see The menu).

The icon only talks to the proxy on your machine (127.0.0.1) and, to start or stop it, to the service installed on this machine.

Where to find it

  • Windows 10 and 11: in the notification area at the right of the taskbar. Windows often hides new icons behind the ^ arrow ("Show hidden icons"): click it and drag the Tegvia icon onto the taskbar to keep it visible. From the keyboard, press Win+B, then the arrow keys.
  • macOS 11 or newer: in the menu bar, on the right. There is no Dock icon.
  • Linux (x86_64, aarch64, riscv64): in the system tray of your desktop (KDE Plasma, XFCE, Cinnamon, MATE and others that show StatusNotifier icons). GNOME shows no tray by default: install and enable the AppIndicator and KStatusNotifierItem Support extension (gnome-shell-extension-appindicator), then log out and back in. Without it, the icon does not appear (see Troubleshooting).

The six states

The state is carried by the shape of the badge at the bottom right of the icon, not by colour alone (colour is only an addition on Windows and Linux; on macOS the icon is a single-colour template that the system tints). Hover the icon to read the state in words and the version and port.

State Badge shape Meaning Tooltip (first line)
Active circle with a check Protection is on. Tegvia: protection active
Paused square with two bars Protection was turned off. Requests are relayed without inspection. Tegvia: protection is off
Attention triangle with an exclamation mark The proxy runs but something needs a look: Claude Code settings cannot be updated, or Claude Code does not go through Tegvia. The tooltip gives the cause. Tegvia: attention needed, cause
Stopped outlined circle with a cross; the Tegvia symbol stays whole but dimmed The proxy does not answer. Tegvia: the proxy is not responding
Starting open arc (three quarters of a circle) Waiting for the first answer, for up to 15 seconds after the icon starts (longer while the icon is starting the service). Tegvia: starting...
Error diamond with a horizontal bar Tegvia could not start: the service's start command failed. Tegvia: could not start (code N)

The second line of the tooltip is always Tegvia <version> · port <port>. The icon only shows "Stopped" after two failed checks in a row (about 10 seconds), so a brief hiccup does not flash it. Texts follow the language of the proxy (French or English); if the proxy does not answer, the language of your system is used.

The Error state appears when the start the icon makes at launch fails, or when Service > Start fails while the icon already shows Error. A Service > Start that fails from any other state (for example Stopped) only shows the usual failure notification, and the icon stays Stopped. The tooltip shows the exit code of the start command (most often 1; do not rely on a specific value) and a single "Service action failed" notification shows that code. The menu behaves as in the Stopped state, but Service > Start stays usable. The state goes away as soon as Tegvia answers. To find the cause, read tray.log and proxy.stderr.log (see Troubleshooting).

Linux and macOS limitation: if the service manager accepts the start but Tegvia then fails (for example because the port is already in use), the icon shows Stopped, not Error, with no failure notification. Error then only appears when the start command itself fails. Check the logs, fix the cause, then use Service > Start. On Windows, a busy port does show Error; the scheduled task is also retried up to 3 times (see Service).

Expired version

When the version has an end date (see Evaluation expiry):

  • In the last 30 days, the menu shows a disabled line after the status line ("Evaluation expires on date (in N days)", "(tomorrow)", or "Evaluation expires today (date)"), and one notification per day is titled "Tegvia evaluation ends in N days" (or "ends tomorrow", "ends today") with the date and the contact address (hello@tegvia.tech). That notification follows the Notifications option: when it is off, nothing is sent.
  • Once expired, the "Stopped", "Starting" and "Error" states are replaced by Expired version (tooltip "Tegvia: version expired", same badge as Stopped). Service > Start and Restart are disabled, and the icon no longer starts the service at launch. Documentation opens the documentation of the archive folder (docs/index.html), since the proxy that usually serves it is not running; it is greyed out if that file is missing. Get a new version from hello@tegvia.tech.

The menu

A menu action takes effect within about a second.

Open the menu with a right click (Windows), or a click (macOS and Linux). On Windows, a left click opens the console directly; on Linux, depending on your desktop, a click can also open the console.

  1. Status line: the same sentence as the tooltip. Not clickable.
  2. Open console: opens http://127.0.0.1:<port>/tegvia/ui/ in your browser.
  3. Protection (checked when on): unchecking it opens a submenu with a single entry, Turn protection off, which acts as the confirmation. Turning protection back on is a single click. It does the same as the switch in Settings. The entry is disabled while the icon is Stopped or Starting, and when the settings of Claude Code cannot be updated.
  4. Latest alerts: up to five rows HH:MM · module (local time, newest first) for the latest blocked requests and tool calls. Clicking a row opens the console. With nothing to show the row reads "No alerts". With an older proxy that does not offer alerts, it reads "Latest alerts (proxy too old)" and is disabled.
  5. Notifications (submenu): Notifications (on or off) and Also notify warnings (see below). Your choices are remembered.
  6. Service (submenu Start, Stop, Restart): only shown when the background service is installed on this machine. The three entries are greyed while a command runs (up to 30 seconds) and extra clicks are ignored. When it ends, a notification says "Service started", "Service stopped" or "Service restarted"; if it fails or takes more than 30 seconds, the notification gives the exit code only.
  7. Documentation: opens the documentation served by the proxy.
  8. About: the version of the icon and, if different, of the proxy.
  9. Quit Tegvia: closes the icon and stops Tegvia.
    • When the background service is installed and active, the entry opens a confirmation sub-menu: a greyed line (French text "Tegvia ne vous protégera plus tant que vous ne l’aurez pas relancé."; in English "Tegvia will stop protecting you until you launch it again."), Stop Tegvia and quit and Cancel. Stop Tegvia and quit stops the service (the proxy, the port and the Claude Code redirect) then closes the icon, after 30 seconds at most; if the stop fails, the icon closes anyway and the code is only written to tray.log. Cancel changes nothing.
    • In the other cases (service not installed, stopped or of unknown status, Tegvia launched by hand or by the standalone launcher), the entry is plain: one click closes the icon, with no confirmation, and nothing is stopped.

When the icon is Stopped, Error or Starting, Open console, Protection, Latest alerts and Documentation are disabled. Nothing in the menu starts the proxy, except Service > Start when the service is installed.

Notifications

The icon sends a native OS notification:

  • when Tegvia blocks a request (title "Tegvia blocked a request") or a tool call (title "Tegvia blocked a tool call"). The text is only the name of the module and the time, for example secret_scan · 14:32;
  • once, when protection goes off ("Tegvia protection is off"), when the proxy stops answering ("Tegvia proxy is not responding"), and when protection is back ("Tegvia protection is back on");
  • when a service command succeeds ("Service started", "Service stopped", "Service restarted");
  • when a menu action fails ("Could not change protection", "Service action failed"), with an error code only.

A notification never shows the reason of a block, the content of the request, a file path, a command or a secret. For the detail, open the console (on Windows and Linux, clicking the notification opens it).

During a burst of blocks, the first three in a 10 second window are shown one by one, and the others are grouped in one notification ("N more requests blocked").

Warnings (alerts below the blocking level) are off by default. Tick Notifications > Also notify warnings to receive them too. Untick Notifications to receive none; the warnings entry is then disabled. The icon and the menu keep updating either way. Your operating system's Do Not Disturb (macOS Focus, Windows Focus Assist, desktop "do not disturb") applies as for any other notification.

Starting the icon

install (background service) also sets up the icon to start at login and starts it right away. Pass --no-tray to install the service only:

./install.sh --no-tray            # Linux, macOS
install.cmd --no-tray             # Windows
System Autostart entry
Linux ~/.config/autostart/io.tegvia.tray.desktop
macOS LaunchAgent ~/Library/LaunchAgents/io.tegvia.tray.plist (graphical sessions only)
Windows the Tegvia value under HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run

On every system, a problem with the icon never makes install fail: it prints the reason and the service is installed anyway. When the icon cannot run on this machine (for example plain GNOME without the AppIndicator extension), install writes no autostart entry and prints a single message giving the reason and the steps to enable the extension: run install again once fixed. install --no-tray does not remove an entry that already exists (see Troubleshooting). Tegvia never overwrites an entry it did not create. uninstall removes the autostart entry and closes the icon.

To start the icon by hand, for example without the service or after quitting it:

System Command
Linux, macOS sh launch/tegvia-tray.sh
Windows launch\tegvia-tray.cmd

An icon started at login, or by install, uses the installed port. An icon started by hand uses 8736, unless TEGVIA_PORT is set to the same port in that shell.

Starting it twice is harmless: the second launch prints "Tegvia icon is already running." and exits (Linux and macOS). On Windows the launcher starts the icon detached and prints nothing, so the message and any startup problem are only in %USERPROFILE%\.tegvia\state\tray.log.

Launching the icon also starts Tegvia when the service is installed and stopped (a single attempt; the icon shows Starting, and no notification on success). If the service is already running, absent or of unknown status, launching starts nothing.

The icon is not restarted automatically. After Quit Tegvia, Tegvia stays stopped until the icon is next launched or you next log in. To bring it back right away, launch the icon by hand (sh launch/tegvia-tray.sh or launch\tegvia-tray.cmd).

Linux and macOS: dependencies

On Linux and macOS the icon needs a small extra set of Python libraries (installed into the .deps/ folder of Tegvia at the first start, like the proxy's, from the hash-locked requirements-tray.txt). It installs them by itself (network access to PyPI needed). Windows needs nothing extra.

WSL

WSL has no tray. Run the icon on the Windows side, with launch\tegvia-tray.cmd: it reaches the proxy running in WSL through localhost. On WSL itself, install does not install the icon and says so, and the Service entry is not shown (Windows cannot control a WSL service).

Supported systems

System Supported
Linux x86_64, aarch64, riscv64, in a graphical session (X11 or Wayland) with a tray host
macOS 11 or newer (Intel and Apple silicon)
Windows 10 and 11 (x64 and ARM64)

Anywhere else the icon prints the reason and exits with code 3, without any dialog. This also happens on WSL, without a graphical session, on GNOME without the AppIndicator extension, or when its dependencies cannot be installed. Nothing else is affected: the proxy and the protection do not depend on the icon. The reason is on screen when launched by hand on Linux and macOS, and in ~/.tegvia/state/tray.log (on Windows, only there).

Limitations

  • macOS notifications appear under the name Script Editor (that is how they are sent) and cannot be clicked to open the console: use the menu.
  • GNOME needs the AppIndicator extension (see above); without it there is no icon.
  • The menu may refresh late. On some desktops an open menu only shows changes the next time you open it.
  • No automatic relaunch of the icon: use install, or the manual launcher.
  • No visible icon (WSL, Linux without a graphical session, GNOME without AppIndicator): the service still starts at login, but nothing starts it when the icon launches and no entry quits it; stop it with stop (see Service).
  • Linux and macOS: a start that is accepted but whose proxy then fails shows Stopped, not Error (see above).
  • Standalone launcher without the service: the menu has no Service entry.
  • The icon follows the port of the installed service (8736 by default, or the one chosen with install --port N; see Choosing the port). When install moves the service to another port, it restarts the icon on that port; if it cannot, it prints "Tray icon: the running icon could not be restarted on port N; quit it, then run install again (or log out and back in)." In that case quit the icon, then run install again or log out and back in; do not start it by hand, as an icon started by hand uses 8736 unless TEGVIA_PORT is set to the same port in that shell. It does not control a proxy on another machine.

See also Troubleshooting.

Files

The icon keeps its settings in ~/.tegvia/state/tray.json (your notification choices) and logs to ~/.tegvia/state/tray.log (a rotating file, never any request content). An unexpected crash of the icon is recorded there too. The folder is the data folder.

Third-party notices

The icon uses, on Linux, dbus-fast and, on macOS, PyObjC (the Cocoa framework binding). Both are released under the MIT licence. Windows uses only the Python standard library. Their full licence texts come with the installed packages in the .deps/ folder.