Aller au contenu

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 install dans 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 " ; install les refuse. Sur tous les systèmes, install refuse 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 :

  1. --port N ;
  2. la variable d'environnement TEGVIA_PORT, si elle contient un port valide ;
  3. le port de l'installation précédente (un simple install relancé conserve donc votre port) ;
  4. le port par défaut, 8736.

  5. Un --port hors de 1024-65535, ou qui n'est pas un nombre, est refusé avec un message d'usage et le code de sortie 2.

  6. Si vous donnez --port et un TEGVIA_PORT différent, install refuse (code de sortie 3) avec un message qui nomme les deux valeurs. Retirez l'un des deux ou donnez-leur la même valeur.
  7. Un TEGVIA_PORT qui 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). ou Uninstall failed (see above). (pour uninstall)

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.log et proxy.stderr.log dans le dossier de données (~/.tegvia) ; status en affiche les chemins.
  • state/install.log dans le dossier de données : ce que install et uninstall ont affiché, exécution après exécution (voir ci-dessus).
  • Le journal du gestionnaire de services : journalctl --user -u tegvia sous 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.json jusqu'au prochain démarrage. Utilisez stop, restart ou uninstall, 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é par install, jamais exécuté.
  • Windows refuse les chemins contenant % ou ", et un TEGVIA_HOME demande setx.
  • Windows, attente de Entrée : install.cmd et uninstall.cmd attendent 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 < nul pour é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.