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 withinstall --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¶
-
Open a terminal in the Tegvia folder (the one that contains
install.shandinstall.cmd). Keep that folder where it is: the service points at it. On macOS, it must not be in~/Downloads,~/Documents,~/Desktopor iCloud Drive (use for example~/tegvia), because macOS restricts what a background service may read there. -
Run the installer:
System Command Linux, WSL, macOS ./install.sh(orsh install.sh)Windows install.cmd(double-click, or fromcmd.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_URLin~/.claude/settings.json). All the details, options (--dry-run) and system-specific notes are on the Background service page. -
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 statuson Windows): the service should be installed and active, andsettings.jsonshould 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).