Installation from an archive¶
Tegvia can be handed over as a zip
archive (tegvia-<name>.zip), for example by your administrator. The
archive contains everything needed to run Tegvia standalone, as a
background service or on demand, and
this documentation as a ready-to-open website.
What you receive¶
| File | Role |
|---|---|
tegvia-<name>.zip |
The archive itself. |
tegvia-<name>.zip.sha256 |
Its SHA-256 fingerprint, to check it was not damaged or altered on the way. |
Read the archive name¶
<name> is the Tegvia version the archive was built from:
| Name | Meaning |
|---|---|
v1.2 |
The release v1.2, exactly. |
v1.2-3-gabc1234 |
A build made 3 commits after release v1.2, from the commit starting with abc1234. Not an official release. |
abc1234 |
No release is known: only the commit hash is available. |
...-dirty |
The build included changes that were not yet committed. Not reproducible: do not use it in production. |
...-unaudited |
The security audit of the dependencies was skipped (see the build report). |
Prefer archives named after a plain release (v1.2).
Verify the archive¶
Put the .zip and the .zip.sha256 file in the same folder, then compare
the fingerprint.
Linux
sha256sum -c tegvia-<name>.zip.sha256
macOS
shasum -a 256 -c tegvia-<name>.zip.sha256
Windows (cmd.exe or PowerShell)
certutil -hashfile tegvia-<name>.zip SHA256
On Linux and macOS the command must answer OK. On Windows, compare the
printed value with the one in the .zip.sha256 file (the text before the
file name): they must be identical. If they differ, do not use the archive
and ask for a new copy.
Extract to a stable folder¶
Extract the archive to the folder where Tegvia will stay, for example
~/tegvia or C:\Tegvia. The archive holds a single folder,
tegvia-<name>/. The background service points at this folder: if you move
or delete it, the service stops working (run install again after moving).
On macOS, do not extract into ~/Downloads, ~/Documents, ~/Desktop or
iCloud Drive (~/Library/Mobile Documents): macOS restricts what a
background service may read in those folders, so a service installed from
there may never become active. Use a folder such as ~/tegvia instead.
| Folder | On macOS |
|---|---|
~/Downloads/tegvia-<name> |
Not suitable: the install prints a warning |
~/tegvia |
Suitable |
Before extracting, deal with the operating system warnings below if they apply to you.
macOS: Gatekeeper¶
A file downloaded from the Internet is "quarantined". Double-clicking
launch/tegvia.command can then be refused ("cannot be opened because it is
from an unidentified developer"). What to do depends on your macOS version:
- macOS 15 (Sequoia) or newer: right-click then Open no longer
bypasses the block. Try to open the file once, then go to System
Settings, Privacy & Security, scroll down to the message about
tegvia.commandand click Open Anyway, then confirm. - macOS 14 (Sonoma) or older: right-click the file, choose Open, then confirm.
-
Any version: remove the quarantine from the whole extracted folder in Terminal. This is the most reliable way:
xattr -dr com.apple.quarantine <extracted folder>
Running ./install.sh from Terminal (the recommended
installation) is not blocked by Gatekeeper; this section only
concerns double-clicking launch/tegvia.command.
Windows: SmartScreen and "from the Internet" mark¶
Windows marks a downloaded zip, and what is extracted from it, as coming from
the Internet. SmartScreen may then warn when you run install.cmd or
launch\tegvia.cmd. Remove the mark before extracting: right-click the
zip, Properties, tick Unblock, OK. Or, after extracting, in
PowerShell:
Get-ChildItem -Recurse <extracted folder> | Unblock-File
If SmartScreen still shows a warning, choose More info then Run anyway, provided you verified the fingerprint.
Install and run¶
You need Python 3.11 or newer with pip (see
Installation) and, on the first launch, network access
to PyPI: the dependencies are downloaded into a .deps/ folder inside the
Tegvia folder. Nothing else is installed.
Choose one way, from the extracted folder. Do not run the service and the launcher together (see Standalone deployment).
| Mode | Linux, WSL | macOS | Windows |
|---|---|---|---|
| Background service (starts at login) | ./install.sh |
./install.sh |
install.cmd |
| On demand, tied to a window | sh launch/tegvia.sh |
launch/tegvia.command |
launch\tegvia.cmd |
The service is the recommended way, see Background service. On a
desktop it also sets up the system tray icon; use
--no-tray to skip it. The archive contains the icon and its launchers
(launch/tegvia-tray.sh, launch\tegvia-tray.cmd); on Linux and macOS the icon
also needs requirements-tray.txt, without which an archive build is refused.
Then restart Claude Code so that it goes through the proxy.
The documentation is in the archive: open docs/index.html in your browser
(it works without a network connection, search included).
Evaluation expiry¶
An archive can be an evaluation version with an end date. The date is fixed
when the archive is built (by default 180 days after the date of the commit it
was built from) and written in the archive's README.txt and in
build_report.txt (expires line; none when the archive has no expiry). The
service's status command also prints it (Evaluation: expires <date> (in N
days)).
Warnings, in the last 30 days.
- The web console shows a banner on every screen.
- The tray icon shows an information line in its menu and sends one notification per day.
- The proxy writes a WARNING line in its log (
proxy.stderr.log) each time it starts.
At expiry. The date itself is still valid; the version is refused from the next day. Tegvia then refuses to start:
- the standalone launcher, the service's
install,startandrestart, andproxy.py --configureprint the message below and exit with code 78 (a configuration error, so the service is not restarted in a loop).proxy.pywithout--configurealso refuses to start, but it does not touchsettings.jsonand its message has no "direct connection" line; - when it is started with the launcher, the service or
--configure, Claude Code is put back on a direct connection to the Anthropic API: Tegvia no longer protects it. The redirect in~/.claude/settings.jsonis removed, and your previous value is restored if there was one. Ifsettings.jsoncannot be read, is not valid or not writable, the redirect cannot be removed: the message then has no "direct connection" line, and you must check~/.claude/settings.jsonyourself (see troubleshooting); installis refused before anything is installed (it still removes the redirect, as above).install --dry-runis refused too, and changes nothing at all (it does not touchsettings.jsoneither; its message has no "direct connection" line);uninstall,stopandstatusstill work, so you can always clean up.
Service behaviour at expiry: on Linux (systemd), exit code 78 means the service is not restarted. On macOS (launchd), the service exits with code 0, so there is no restart loop. On Windows (Task Scheduler), the task is retried up to 3 times, printing the same message each time, with no other effect.
This evaluation version of Tegvia expired on 2026-05-01, so it did not start.
Claude Code has been put back on a direct connection to the Anthropic API. Tegvia is no longer protecting it.
To get a new version, contact: hello@tegvia.tech
The message is in English by default, in French when TEGVIA_LANGUAGE=fr is set
in the environment of the launcher (the proxy itself follows its LANGUAGE
setting). If the date written in the archive is not valid, the version is
treated as expired and the first line says so.
Getting a new version: contact hello@tegvia.tech, then follow Update.
For whoever builds the archive: build_dist.py --expires YYYY-MM-DD sets
another end date (not before the commit date), and --no-expiry builds an
archive without any (the two cannot be combined). A reference that predates
this feature builds with a warning and no expiry.
The date is compared with the clock of the machine: this is a reminder to update, not a copy protection.
Update¶
- Remove the service of the old version:
./uninstall.sh(oruninstall.cmd) from the old folder. - Verify and extract the new archive to a stable folder (a new folder, or over the old one once emptied).
- Run
install.sh(orinstall.cmd) from the new folder.
Your logs and settings live in the data folder ~/.tegvia, outside the
archive folder: they are kept. Dependencies are installed again on the first
launch of the new folder.
Uninstall¶
- Run
./uninstall.sh(oruninstall.cmd): it removes the service and the redirect in~/.claude/settings.json. - Delete the extracted folder.
To also remove your logs, delete the data folder ~/.tegvia (see
Uninstall).
The build report¶
The file build_report.txt at the root of the archive says how it was made.
Its main lines:
| Line | Meaning |
|---|---|
version |
The archive name (see above). |
ref |
The release or commit it was built from. |
commit, commit_date |
The exact commit. |
dirty |
yes if it included uncommitted changes. |
audit |
Result of the security audit of the dependencies: passed, or skipped (archive named -unaudited). |
dependencies, vulnerabilities, ignored |
Number of dependencies checked, known vulnerabilities found, and known vulnerabilities knowingly accepted (listed under [ignored] with their reason and expiry date). |
An archive is only built when the audit finds no unaccepted vulnerability, so
vulnerabilities is 0 in a delivered archive.
The audit reports every known vulnerability. The build then sets aside those
that the maintainers accepted in audit-ignore.toml, each with a reason and an
expiry date: a vulnerability is accepted when its identifier, or any of its
aliases (for example a CVE number), matches a valid entry. An expired entry no
longer protects anything and the build fails.
Every file of the archive carries the date of the commit it was built from, not the date of the build.
If a build is refused (for example because of uncommitted changes without
--allow-dirty), the report written next to it has a version ending in
-dirty. If the build cannot write its files (disk full, missing permission),
it stops with an error message naming the cause and leaves no partial archive.
Troubleshooting¶
- macOS refuses to open
tegvia.command: see Gatekeeper. - Windows shows "Windows protected your PC": see SmartScreen.
- Files cannot be run after extraction on Linux/macOS: use
sh install.sh(orsh launch/tegvia.sh), or extract withunzip, which keeps the executable permissions. - The service no longer starts after moving the folder: run
installagain from the new location. See Background service. - "no usable system Python 3.11+ found on PATH" or "dependency install failed": see Troubleshooting.