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.
- Status line: the same sentence as the tooltip. Not clickable.
- Open console: opens
http://127.0.0.1:<port>/tegvia/ui/in your browser. - 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.
- 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. - Notifications (submenu): Notifications (on or off) and Also notify warnings (see below). Your choices are remembered.
- 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.
- Documentation: opens the documentation served by the proxy.
- About: the version of the icon and, if different, of the proxy.
- 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 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
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). Wheninstallmoves 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 runinstallagain or log out and back in; do not start it by hand, as an icon started by hand uses 8736 unlessTEGVIA_PORTis 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.