Service en arrière-plan¶
Le service installe Tegvia comme service utilisateur (sans droits
administrateur ni sudo). Il démarre le proxy à l'ouverture de session, le
relance s'il s'arrête de façon inattendue, et se pilote par une commande
unique sous Linux, WSL, macOS et Windows. C'est la manière par défaut de
lancer Tegvia ; pour ne l'exécuter que tant qu'une fenêtre reste ouverte,
voir le lanceur autonome.
| Système | Mécanisme | Définition |
|---|---|---|
| Linux, WSL | unité systemd --user |
~/.config/systemd/user/tegvia.service |
| macOS | LaunchAgent | ~/Library/LaunchAgents/io.tegvia.proxy.plist |
| Windows | tâche planifiée, déclencheur « à l'ouverture de session » | tâche Tegvia de votre compte |
Tant qu'il tourne, le service fait pointer ~/.claude/settings.json vers le
proxy (env.ANTHROPIC_BASE_URL) et retire cette redirection à chaque arrêt du
proxy : votre valeur précédente est toujours rétablie.
Vous avez reçu Tegvia sous forme de fichier zip ? Voir Installation depuis une archive.
Prérequis¶
- Python 3.11 ou plus récent (voir Installation). Les
dépendances sont installées au premier
installdans un dossier.deps/du dossier Tegvia (accès réseau à PyPI nécessaire). - Port 8736 (le port par défaut) libre sur
127.0.0.1, sauf s'il s'agit déjà du service Tegvia. Si 8736 est pris, choisissez un autre port avec--port. - Linux et WSL : un gestionnaire systemd utilisateur fonctionnel (voir WSL).
- Windows : les chemins (Python et dossier Tegvia) ne doivent
pas contenir
%ni de guillemet";installles refuse. Sur tous les systèmes,installrefuse aussi un chemin relatif pour Python ou le dossier Tegvia (cas rare).
Installation¶
Depuis le dossier Tegvia (fonctionne depuis n'importe quel dossier courant) :
| Système | Commande |
|---|---|
| Linux, WSL, macOS | ./install.sh (ou sh install.sh) |
| Windows | install.cmd (double-clic, ou depuis cmd.exe) |
install ne pose aucune question. Il vérifie Python et le port, installe les
dépendances si besoin, écrit la définition du service, le démarre et attend
jusqu'à 15 secondes que le proxy réponde. Il affiche ensuite l'URL de la
console web (http://127.0.0.1:<port>/tegvia/ui/, 8736 sauf autre choix) et l'emplacement des
journaux. Si le proxy ne répond pas à temps, il affiche la fin de
proxy.stderr.log et sort avec un code non nul. Sous Linux, WSL et macOS,
install (et restart) ne signalent un succès que si le proxy répond et
que le gestionnaire de services indique que le service tourne.
Ajoutez --dry-run pour voir ce qui serait écrit sans rien modifier :
./install.sh --dry-run (le port qui serait utilisé est aussi affiché).
Choisir le port¶
Par défaut, le service écoute sur le port 8736. Pour en utiliser un autre,
ajoutez --port N (un nombre entier de 1024 à 65535) :
./install.sh --port 9123
install.cmd --port 9123
install choisit le port dans cet ordre et affiche une ligne Port: avec la
valeur et son origine :
--port N;- la variable d'environnement
TEGVIA_PORT, si elle contient un port valide ; - le port de l'installation précédente (un simple
installrelancé conserve donc votre port) ; -
le port par défaut, 8736.
-
Un
--porthors de 1024-65535, ou qui n'est pas un nombre, est refusé avec un message d'usage et le code de sortie 2. - Si vous donnez
--portet unTEGVIA_PORTdifférent,installrefuse (code de sortie 3) avec un message qui nomme les deux valeurs. Retirez l'un des deux ou donnez-leur la même valeur. - Un
TEGVIA_PORTqui n'est pas un port valide est ignoré, avec un avis d'une ligne, et le choix passe à la règle suivante.
Changer de port plus tard : relancez install --port N. Le service est
redémarré sur le nouveau port, ~/.claude/settings.json est mis à jour pour
pointer vers lui et la redirection vers l'ancien port est retirée. Redémarrez
ensuite Claude Code. Relancer install --port 8736 ramène le service au port
par défaut. status affiche le port installé (une ligne Port:, port dans
le JSON), et les autres commandes (start, stop, restart, uninstall)
agissent toujours sur le port du service installé.
install configure aussi l'icône de la zone de notification
(entrée de lancement automatique à l'ouverture de session, et l'icône est
lancée tout de suite). Ajoutez --no-tray pour n'installer que le service :
./install.sh --no-tray (install.cmd --no-tray). Un problème avec l'icône
(système non pris en charge, GNOME sans l'extension AppIndicator, WSL...) est
affiché mais ne change jamais le code de sortie, et le service est installé
quand même.
Si vous changez de port avec --no-tray, l'entrée de lancement automatique de
l'icône garde l'ancien port (elle n'est pas mise à jour). Réinstallez sans
--no-tray pour que l'icône suive le nouveau port.
Ce que vous voyez à la fin, et install.log¶
install et uninstall se terminent par une ligne de résumé (en anglais) :
Tegvia installed.Tegvia installed, but the tray icon reported a problem (see above).(le service est installé ; seule l'icône a échoué)Installation failed (see above).Dry run finished; nothing was changed.(avec--dry-run)Tegvia removed.,Tegvia removed, but the tray icon reported a problem (see above).ouUninstall failed (see above).(pouruninstall)
Tout ce que la commande affiche est aussi enregistré dans install.log, et la
ligne de résumé se termine par Install log: <chemin>. Le fichier est dans le
dossier state du dossier de données : ~/.tegvia/state/install.log sous
Linux, WSL et macOS, %USERPROFILE%\.tegvia\state\install.log sous Windows
(sous TEGVIA_HOME si vous l'avez défini). Chaque exécution ajoute un bloc
qui commence par une ligne d'en-tête (date, commande, système, Python, dossier
Tegvia, version) et se termine par une ligne === exit <code>: ... ===. Le
fichier ne contient aucun secret (seulement ce qui a été affiché, plus l'en-tête), n'est lisible que par vous sous Linux, WSL et
macOS, et reste petit (au-delà d'environ 1 Mio, la partie la plus ancienne est
supprimée ; une exécution en enregistre au plus 256 Kio). Si le journal ne peut
pas être écrit, un avertissement s'affiche et l'installation continue sans
être affectée.
Sous Windows, install.cmd et uninstall.cmd laissent la fenêtre ouverte
après le résumé : elle affiche Press Enter to close this window. pour que
vous puissiez lire le résultat après un double-clic.
Lancer install deux fois met simplement la définition à jour, sans doublon.
Tegvia n'écrase jamais une définition qu'il n'a pas générée (fichier ou tâche
du même nom sans le marqueur de Tegvia) : il refuse et vous le dit.
Redémarrez Claude Code après la première installation pour que les nouvelles sessions lisent la redirection.
Si vous définissez TEGVIA_HOME (chemin absolu) avant install, le service
l'enregistre. Sous Windows, la tâche ne voit pas une variable définie
seulement dans votre shell : lancez d'abord setx TEGVIA_HOME "C:\votre\dossier",
ouvrez ensuite une nouvelle fenêtre (ou double-cliquez sur install.cmd)
pour que la variable soit visible, puis lancez install.cmd ; sinon install refuse et affiche cette commande.
Commandes courantes¶
La commande complète est launch/tegvia-service.sh (Linux, WSL, macOS) ou
launch\tegvia-service.cmd (Windows), suivie de :
| Sous-commande | Effet |
|---|---|
install [--dry-run] [--no-tray] [--port N] |
Installer et démarrer (voir ci-dessus), avec l'icône de la zone de notification sauf --no-tray ; --port choisit le port. |
uninstall |
Arrêter, retirer la redirection, supprimer la définition, retirer le lancement automatique de l'icône et la fermer. |
start |
Démarrer le service (sans effet s'il tourne déjà). |
stop |
L'arrêter et restaurer settings.json. Pas de relance automatique. |
restart |
Arrêter puis redémarrer. Attend que le proxy réponde et affiche le journal d'erreurs sinon. |
status [--json] |
Afficher l'état. |
sh launch/tegvia-service.sh status
sh launch/tegvia-service.sh restart
Chaque sous-commande est idempotente. Sans sous-commande, ou avec une sous-commande inconnue, l'aide s'affiche et le code de sortie est non nul.
status indique si le service est installé et actif, son identifiant de
processus, le dernier code de sortie (Linux, WSL et macOS uniquement ; sous Windows,
« actif » signifie que le proxy répond sur son port en tant que service, et
ni identifiant de processus ni code de sortie n'est affiché), le deployment rapporté par le proxy
(service si tout va bien), si settings.json est redirigé, l'URL de la
console, les chemins des journaux et, quand rien n'écoute sur le port, la fin
de proxy.stderr.log. Il ne demande aucune dépendance et fonctionne même si
votre config.py est cassé. --json affiche les mêmes informations en JSON
pour les scripts. Si le Python ou le dossier Tegvia enregistrés dans la
définition n'existent plus (déplacés ou supprimés), status le signale et
conseille de relancer install. Il affiche aussi une ligne Icon: (tray
dans le JSON) : running, installed (lancement automatique configuré,
icône non lancée en ce moment), unavailable avec la raison, ou absent.
Mise à jour¶
Après une mise à jour du dossier Tegvia (par exemple git pull), lancez
restart pour que le service charge la nouvelle version. restart suffit
même si les dépendances ont changé : Tegvia installe le nouvel ensemble dans
son propre dossier sous .deps, puis bascule dessus. Si cette installation
échoue (par exemple hors ligne), il continue avec l'ensemble précédent et vous
le signale (voir Dépannage) ;
relancez restart une fois en ligne. Les anciens ensembles sont supprimés
automatiquement après une installation réussie. Les fichiers laissés en vrac à
la racine de .deps par les anciennes versions ne sont plus utilisés : vous
pouvez les supprimer à la main.
Désinstallation¶
| Système | Commande |
|---|---|
| Linux, WSL, macOS | ./uninstall.sh |
| Windows | uninstall.cmd |
Elle arrête le service, vérifie que settings.json est revenu à son état
d'origine (et le corrige sinon), puis retire la définition. Elle retire aussi
l'entrée de lancement automatique de l'icône (seulement si Tegvia l'a créée)
et ferme l'icône, même si le service lui-même n'était pas installé. Votre dossier
de données (~/.tegvia), la base de logs et votre config.py ne sont jamais
supprimés ; la commande le dit. Sur un service non installé, elle réussit
avec un message.
Version d'évaluation expirée¶
Sur une version d'évaluation expirée,
install, start et restart sont refusés avec le code de sortie 78 et un
message donnant la date et hello@tegvia.tech ; install --dry-run est refusé
aussi et ne modifie rien. uninstall, stop et status fonctionnent toujours ;
status affiche la date de fin (Evaluation: expires ... ou expired on ...).
Journaux¶
proxy.stdout.logetproxy.stderr.logdans le dossier de données (~/.tegvia) ;statusen affiche les chemins.state/install.logdans le dossier de données : ce queinstalletuninstallont affiché, exécution après exécution (voir ci-dessus).- Le journal du gestionnaire de services :
journalctl --user -u tegviasous Linux et WSL ; l'historique de la tâche dans le Planificateur de tâches sous Windows.
Démarrer au boot plutôt qu'à la connexion (Linux)¶
Par défaut, un service systemd utilisateur démarre à votre connexion et s'arrête à la fin de votre dernière session. Pour qu'il démarre au démarrage de la machine, lancez une fois, vous-même :
loginctl enable-linger $USER
install affiche cette commande mais ne la lance jamais : elle modifie
l'état de la machine et demande votre accord explicite (et peut exiger des
droits d'administrateur selon le système). Effet : vos services utilisateur
démarrent au boot sans connexion et continuent après la déconnexion.
WSL¶
Sous WSL, le service exige que systemd soit activé dans la distribution. Sinon
install n'écrit rien et indique quoi faire : ajoutez
[boot]
systemd=true
dans /etc/wsl.conf de la distribution, puis lancez wsl --shutdown depuis
Windows et rouvrez la distribution.
Une distribution WSL ne démarre qu'au premier appel wsl (ouverture d'un
terminal WSL, commande wsl). Tant qu'il n'a pas eu lieu, le service ne
tourne pas, même avec enable-linger. Claude Code lancé depuis Windows ne
passe donc par un service WSL qu'une fois la distribution démarrée par un
appel wsl.
Relances et fenêtre de relance¶
À chaque arrêt du proxy (arrêt, plantage, redémarrage), la redirection de
settings.json est retirée ; au démarrage suivant, le proxy la rétablit.
Pendant les quelques secondes d'une relance, les nouvelles sessions Claude
Code vont directement vers l'API Anthropic, sans Tegvia. C'est voulu : un
proxy mort ne casse jamais une session. Les sessions déjà ouvertes gardent
leur adresse et échouent tant que le proxy n'est pas revenu.
Politique de relance automatique :
| Système | Politique |
|---|---|
| Linux, WSL | relance après un échec, 3 s plus tard, au plus 5 fois par minute |
| macOS | relance sur sortie non nulle, au moins 5 s d'intervalle |
| Windows | configuré pour 3 essais au plus, à 1 minute d'intervalle (non garanti, voir ci-dessous) |
Sous Windows, la relance automatique après un plantage n'est pas garantie. Si
le service reste arrêté après un plantage, lancez
launch\tegvia-service.cmd start (ou restart).
Un arrêt demandé (stop, systemctl --user stop, fin de la tâche depuis le
gestionnaire, sauf le cas ci-dessous) n'est jamais suivi d'une relance.
Port déjà utilisé¶
Si un autre processus utilise déjà le port choisi (8736 par défaut), install
refuse (sauf s'il s'agit du service Tegvia lui-même) ; choisissez-en un autre
avec install --port N. Si cela arrive au démarrage du service (à
la connexion par exemple), c'est une erreur de configuration, sans boucle de
relance ; le message est dans proxy.stderr.log (et, sous Linux et WSL, dans
journalctl --user -u tegvia) :
- Linux, WSL : le service s'arrête et n'est pas relancé.
- macOS : le service sort proprement et n'est pas relancé.
- Windows : le Planificateur est configuré pour réessayer jusqu'à 3 fois, à
1 minute d'intervalle, puis s'arrête ; s'il reste arrêté, lancez
launch\tegvia-service.cmd start.
Dans ce cas, le service retire aussi toute redirection restante de
settings.json avant de s'arrêter : les nouvelles sessions Claude Code vont
directement vers l'API, jamais vers le programme qui occupe le port.
Libérez le port (voir Dépannage) puis
lancez start.
Quand la protection est coupée¶
Si la protection a été coupée depuis la console, un redémarrage du
service la laisse coupée : le proxy relaie sans inspecter et settings.json
n'est pas touché. Réactivez-la depuis la console.
Limites¶
- Fenêtre de relance : voir ci-dessus.
- Windows, arrêt depuis le Planificateur : terminer la tâche depuis la
fenêtre du Planificateur de tâches laisse la redirection dans
settings.jsonjusqu'au prochain démarrage. Utilisezstop,restartouuninstall, qui nettoient correctement. - Windows, fermeture de session ou arrêt : fermer la session ou arrêter Windows peut aussi laisser la redirection en place jusqu'au prochain démarrage du service.
- Superviseur tué (macOS) : si le processus qui supervise le proxy
est lui-même tué de force, le proxy peut continuer orphelin et garder le
port ; tuez-le (voir
Déploiement autonome), puis
start. - WSL ne démarre qu'au premier appel
wsl; linger est seulement affiché parinstall, jamais exécuté. - Windows refuse les chemins contenant
%ou", et unTEGVIA_HOMEdemandesetx. - Windows, attente de Entrée :
install.cmdetuninstall.cmdattendent Entrée dès qu'ils ont une console où lire, y compris lancés depuis un script dans une fenêtre de console. Ils n'attendent pas sans console (tâche planifiée) ou avec une entrée redirigée ; ajoutez< nulpour éviter l'attente (install.cmd < nul). - L'icône de la zone de notification n'est pas relancée automatiquement et n'est pas disponible sous WSL (lancez-la côté Windows) : voir Icône de la zone de notification. Lancer l'icône démarre le service s'il est installé et arrêté (une seule fois, sans nouvelle tentative), et Quitter Tegvia dans son menu arrête le service, après confirmation.
Voir aussi Dépannage.