Skip to content

Installation

Tegvia installs as a background service of your account: it starts the proxy when you log in, restarts it if it stops unexpectedly, and configures Claude Code to go through it. One command does it all, with no administrator rights.

Two alternatives exist: the standalone launcher, which runs Tegvia only while its window stays open, and the installation from an archive if you received Tegvia as a zip file.

Requirements

  • Claude Code installed.
  • Python 3.11 or newer, on the PATH (see below).
  • Network access to PyPI on first install (dependency install).
  • Port 8736 free on 127.0.0.1. If it is taken, install the service on another port with install --port N (see Choosing the port).

Python 3.11 or newer

Tegvia needs a "system" Python 3.11 or newer on the PATH. Python copies inside a virtual environment (.venv) are deliberately ignored. Tegvia also finds a python3.11 (or python3.12, ...) installed next to an older python3: you do not have to replace the system Python.

Check your version:

python3 --version
python3.11 --version

On Windows, use python --version. If either command shows 3.11 or newer, you are done. If python3 shows 3.10 or older, install a newer Python as below. Tegvia then uses it on its own, even if python3 still points at the old one.

Windows

Install Python from python.org and tick "Add Python to PATH". Then open a new terminal and run python --version.

macOS

Either install Python from python.org, or with Homebrew:

brew install python@3.12

Check with python3 --version (or python3.12 --version).

Ubuntu 22.04

The system python3 of Ubuntu 22.04 is 3.10, which is too old. Install a 3.11 beside it (the system python3 is left untouched). The procedure below uses the deadsnakes PPA, a third-party repository widely used for this purpose:

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.11 python3.11-venv
python3.11 --version
python3.11 -m pip --version

Tegvia installs its dependencies with python -m pip, so pip must work for this interpreter. If the last command says No module named pip, run python3.11 -m ensurepip --user, then check again.

Not verified

This Ubuntu 22.04 procedure (deadsnakes packages, and whether python3.11-venv brings pip in) could not be tested when this page was written. If a step fails, check the deadsnakes documentation, and make sure python3.11 -m pip --version works before restarting Claude Code.

Debian 12 or newer, Ubuntu 24.04 or newer

The system Python is already 3.11 or newer: nothing to install for Python. If python3 -m pip --version fails, install pip with sudo apt install python3-pip.

Steps

  1. Open a terminal in the Tegvia folder (the one that contains install.sh and install.cmd). Keep that folder where it is: the service points at it. On macOS, it must not be in ~/Downloads, ~/Documents, ~/Desktop or iCloud Drive (use for example ~/tegvia), because macOS restricts what a background service may read there.

  2. Run the installer:

    System Command
    Linux, WSL, macOS ./install.sh (or sh install.sh)
    Windows install.cmd (double-click, or from cmd.exe)

    It installs the Python dependencies (first time only, up to a minute), writes the service definition, starts the service, waits up to 15 seconds for the proxy to answer, then prints the web console address and the log locations. While it runs, the service points Claude Code at the proxy (env.ANTHROPIC_BASE_URL in ~/.claude/settings.json). All the details, options (--dry-run) and system-specific notes are on the Background service page.

  3. Restart Claude Code. Sessions that were already open keep talking to the API directly; only new sessions go through the proxy.

On Linux, the service starts at login by default; to start it at machine boot instead, see Start at boot. On WSL, systemd must be enabled (see WSL).

Check the installation

  • Run sh launch/tegvia-service.sh status (launch\tegvia-service.cmd status on Windows): the service should be installed and active, and settings.json should point at the proxy.
  • Ask Claude anything: the answer starts with "Protected by Tegvia".

If either check fails, see Troubleshooting. If the proxy does not start, status shows the end of its error log (~/.tegvia/proxy.stderr.log); for a failure at startup (for example a broken config.py), run the standalone launcher in a terminal to see the message.

What the installation changes on your machine

Item Change
~/.claude/settings.json env.ANTHROPIC_BASE_URL points at http://127.0.0.1:8736 (or the port you chose with --port). Any existing value is kept in ANTHROPIC_BASE_URL_TEGVIA_BACKUP.
Tegvia folder .deps/ (Python dependencies) only.
Data folder ~/.tegvia Created when first needed (readable by you only on Linux, WSL and macOS, except on a Windows drive (/mnt/c) under WSL; TEGVIA_HOME changes it). Holds tegvia.db (session logs), state/ (install logs, including install.log), and proxy.stdout.log / proxy.stderr.log (proxy output, each capped at 10 MiB with 3 older copies kept). Under WSL this is the Linux home folder.
Service A per-user service (systemd user unit, LaunchAgent or Task Scheduler task) that runs the proxy, one background Python process that outlives Claude Code.

Nothing else is installed: no administrator rights are needed and the global Python is not changed.

Optional: tray icon

To see the protection state and block notifications in your notification area, use the system tray icon. install sets it up with the background service (add --no-tray to skip it), or you can launch it by hand (launch/tegvia-tray.sh, launch\tegvia-tray.cmd).