Aller au contenu

Installation

Tegvia s'installe comme un service en arrière-plan de votre compte : il démarre le proxy à votre connexion, le relance s'il s'arrête de façon inattendue et configure Claude Code pour passer par lui. Une seule commande suffit, sans droits d'administrateur.

Deux alternatives existent : le lanceur autonome, qui n'exécute Tegvia que tant que sa fenêtre reste ouverte, et l'installation depuis une archive si vous avez reçu Tegvia sous forme de fichier zip.

Prérequis

  • Claude Code installé.
  • Python 3.11 ou plus récent, accessible dans le PATH (voir ci-dessous).
  • Un accès réseau à PyPI lors de la première installation (installation des dépendances).
  • Le port 8736 libre sur 127.0.0.1. S'il est pris, installez le service sur un autre port avec install --port N (voir Choisir le port).

Python 3.11 ou plus récent

Tegvia a besoin d'un Python « système » 3.11 ou plus récent dans le PATH. Les copies de Python situées dans un environnement virtuel (.venv) sont volontairement ignorées. Tegvia trouve aussi un python3.11 (ou python3.12, ...) installé à côté d'un python3 plus ancien : il n'est pas nécessaire de remplacer le Python du système.

Vérifiez votre version :

python3 --version
python3.11 --version

Sous Windows, utilisez python --version. Si l'une de ces commandes affiche 3.11 ou plus, c'est bon. Si python3 affiche 3.10 ou moins, installez un Python plus récent comme ci-dessous. Tegvia l'utilise ensuite tout seul, même si python3 pointe encore vers l'ancien.

Windows

Installez Python depuis python.org en cochant « Add Python to PATH ». Ouvrez ensuite un nouveau terminal et lancez python --version.

macOS

Installez Python depuis python.org, ou avec Homebrew :

brew install python@3.12

Vérifiez avec python3 --version (ou python3.12 --version).

Ubuntu 22.04

Le python3 système d'Ubuntu 22.04 est en 3.10, trop ancien. Installez un 3.11 à côté (le python3 système n'est pas modifié). La procédure ci-dessous utilise le PPA deadsnakes, un dépôt tiers très utilisé à cet effet :

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 installe ses dépendances avec python -m pip : pip doit donc fonctionner pour cet interpréteur. Si la dernière commande répond No module named pip, lancez python3.11 -m ensurepip --user, puis vérifiez à nouveau.

Non vérifié

Cette procédure pour Ubuntu 22.04 (paquets deadsnakes, et le fait que python3.11-venv apporte pip) n'a pas pu être testée lors de la rédaction de cette page. Si une étape échoue, consultez la documentation de deadsnakes, et assurez-vous que python3.11 -m pip --version fonctionne avant de redémarrer Claude Code.

Debian 12 ou plus récent, Ubuntu 24.04 ou plus récent

Le Python du système est déjà en 3.11 ou plus : rien à installer côté Python. Si python3 -m pip --version échoue, installez pip avec sudo apt install python3-pip.

Étapes

  1. Ouvrez un terminal dans le dossier Tegvia (celui qui contient install.sh et install.cmd). Laissez ce dossier à sa place : le service pointe vers lui. Sous macOS, il ne doit pas se trouver dans ~/Downloads, ~/Documents, ~/Desktop ni iCloud Drive (utilisez par exemple ~/tegvia), car macOS restreint ce qu'un service en arrière-plan peut y lire.

  2. Lancez l'installeur :

    Système Commande
    Linux, WSL, macOS ./install.sh (ou sh install.sh)
    Windows install.cmd (double-clic, ou depuis cmd.exe)

    Il installe les dépendances Python (la première fois seulement, jusqu'à une minute), écrit la définition du service, démarre le service, attend jusqu'à 15 secondes que le proxy réponde, puis affiche l'adresse de la console web et l'emplacement des journaux. Tant qu'il tourne, le service fait pointer Claude Code vers le proxy (env.ANTHROPIC_BASE_URL dans ~/.claude/settings.json). Tous les détails, les options (--dry-run) et les remarques propres à chaque système sont sur la page Service en arrière-plan.

  3. Redémarrez Claude Code. Les sessions déjà ouvertes continuent de parler directement à l'API ; seules les nouvelles sessions passent par le proxy.

Sous Linux, le service démarre à la connexion par défaut ; pour qu'il démarre au démarrage de la machine, voir Démarrer au boot. Sous WSL, systemd doit être activé (voir WSL).

Vérifier l'installation

  • Lancez sh launch/tegvia-service.sh status (launch\tegvia-service.cmd status sous Windows) : le service doit être installé et actif, et settings.json doit pointer vers le proxy.
  • Posez une question à Claude : la réponse commence par « Protected by Tegvia ».

Si l'une de ces vérifications échoue, voir Dépannage. Si le proxy ne démarre pas, status affiche la fin de son journal d'erreurs (~/.tegvia/proxy.stderr.log) ; pour un échec au démarrage (par exemple un config.py cassé), lancez le lanceur autonome dans un terminal pour voir le message.

Ce que l'installation modifie sur votre machine

Élément Modification
~/.claude/settings.json env.ANTHROPIC_BASE_URL pointe vers http://127.0.0.1:8736 (ou le port choisi avec --port). Une valeur existante est conservée dans ANTHROPIC_BASE_URL_TEGVIA_BACKUP.
Dossier Tegvia .deps/ (dépendances Python) uniquement.
Dossier de données ~/.tegvia Créé quand il est nécessaire pour la première fois (lisible par vous seul sous Linux, WSL et macOS, sauf sur un lecteur Windows (/mnt/c) sous WSL ; TEGVIA_HOME le change). Contient tegvia.db (journaux de session), state/ (journaux d'installation, dont install.log) et proxy.stdout.log / proxy.stderr.log (sorties du proxy, chacune plafonnée à 10 Mio avec 3 copies plus anciennes conservées). Sous WSL, c'est le dossier personnel Linux.
Service Un service propre à votre compte (unité systemd utilisateur, LaunchAgent ou tâche du Planificateur de tâches) qui exécute le proxy, un processus Python en arrière-plan qui survit à la fermeture de Claude Code.

Rien d'autre n'est installé : aucun droit d'administrateur n'est nécessaire et le Python global n'est pas modifié.

Facultatif : l'icône de la zone de notification

Pour voir l'état de la protection et recevoir des notifications de blocage dans votre zone de notification, utilisez l'icône de la zone de notification. install la configure avec le service en arrière-plan (ajoutez --no-tray pour l'éviter), ou vous pouvez la lancer à la main (launch/tegvia-tray.sh, launch\tegvia-tray.cmd).