Skip to content

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.command and 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, start and restart, and proxy.py --configure print the message below and exit with code 78 (a configuration error, so the service is not restarted in a loop). proxy.py without --configure also refuses to start, but it does not touch settings.json and 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.json is removed, and your previous value is restored if there was one. If settings.json cannot 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.json yourself (see troubleshooting);
  • install is refused before anything is installed (it still removes the redirect, as above). install --dry-run is refused too, and changes nothing at all (it does not touch settings.json either; its message has no "direct connection" line);
  • uninstall, stop and status still 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

  1. Remove the service of the old version: ./uninstall.sh (or uninstall.cmd) from the old folder.
  2. Verify and extract the new archive to a stable folder (a new folder, or over the old one once emptied).
  3. Run install.sh (or install.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

  1. Run ./uninstall.sh (or uninstall.cmd): it removes the service and the redirect in ~/.claude/settings.json.
  2. 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 (or sh launch/tegvia.sh), or extract with unzip, which keeps the executable permissions.
  • The service no longer starts after moving the folder: run install again from the new location. See Background service.
  • "no usable system Python 3.11+ found on PATH" or "dependency install failed": see Troubleshooting.