# doc-project | remote-agent/linux/README.txt | Instructions Linux X11 avec WebRTC P2P, repli HTTP, capture isolee et reprise

REMOTE AGENT TEMPORAIRE - LINUX

Prerequis : Python 3, une session graphique X11 et les bibliotheques systeme X11/XTest disponibles.
Le controle X11 natif reste base sur ctypes. WebRTC utilise une dependance Python locale optionnelle installee par pip ; sur Debian/Ubuntu,
les paquets fournissant libX11, libXinerama et libXtst doivent etre installes par l'administrateur du poste.

1. Decompressez entierement l'archive ZIP.
2. Ouvrez un terminal dans le dossier decompresse.
3. Lancez : sh start.sh
   Le lanceur utilise le chemin physique du dossier, isole Python des PYTHONPATH/PYTHONHOME externes et refuse
   une execution depuis la corbeille. Si ce cas est detecte, decompressez une nouvelle archive dans un dossier normal.
4. Le lanceur verifie automatiquement si une revision plus recente du package est disponible, la telecharge et verifie son SHA-256 avant installation.
5. Si le serveur de mise a jour est temporairement indisponible, la derniere version locale valide est lancee sans bloquer la session.
6. Le client valide ensuite la capture X11 et l'injection XTest avant de creer la session.
7. Le terminal affiche une URL de session unique, reutilisee apres un redemarrage recuperable tant que la session reste valide.
8. Cette URL est automatiquement copiee dans le presse-papiers; transmettez-la uniquement au service ou a l'agent IA que vous autorisez.
9. Si la copie automatique echoue, copiez manuellement l'URL qui reste affichee dans le terminal.
10. Le meme lien peut etre ouvert dans plusieurs navigateurs; un seul detient le bail de controle, les autres restent en lecture seule.
11. Utilisez Ctrl+C pour fermer et revoquer immediatement la session.

Le client utilise X11 pour la capture et XTest pour les entrees. Sous Wayland, la capture et l'injection
globales sont volontairement refusees plutot que de contourner les mecanismes d'autorisation du bureau.
Utilisez une session X11 explicitement autorisee si votre environnement le permet. La variable XDG_SESSION_TYPE
doit alors indiquer x11 et DISPLAY doit designer le serveur X autorise, par exemple :
    printf 'XDG_SESSION_TYPE=%s\nDISPLAY=%s\n' "$XDG_SESSION_TYPE" "$DISPLAY"

Le client refuse Wayland et l'absence de DISPLAY avant de creer une session. Il affiche la version Python,
l'executable, le chemin physique du package, les chemins reels des modules charges, le backend X11 et l'etat des
variables graphiques utiles. La capture native est executee dans un processus worker distinct du processus qui conserve
la session, le heartbeat et les actions distantes. Un crash natif du worker est detecte par l'agent, qui recree le
processus avec un backoff limite et force ensuite une nouvelle frame complete sans perdre la session distante. Des
crashs repetes dans une fenetre courte provoquent un arret controle plutot qu'une boucle de relance infinie. Les jetons
ne sont pas inclus dans ces diagnostics.

Depuis la version 1.3.2, la capture recopie l'en-tete XImage et le framebuffer dans de la memoire Python
avant de detruire l'image native. Les appels X11/XTest de capture et de controle sont serialises afin qu'un
Display ou un XImage ne soit jamais manipule en concurrence par les threads du client.
Depuis la version 1.3.4, la saisie de texte Unicode reserve des keycodes X11 libres et conserve leurs remappages
pendant la session avant de restaurer la disposition a la fermeture. Les applications distantes ne peuvent ainsi plus
interpreter un evenement Unicode avec une disposition deja restauree, notamment pour les caracteres comme À, ô ou Œ.
Depuis la version 1.3.6, l'arret attend la fin des workers reseau, capture et presse-papiers avant la fermeture
des Display X11. Les fermetures HTTP sans reponse sont converties en erreurs temporaires avec backoff, et XImage est
detruit exclusivement via l'API Xlib typee apres copie complete du framebuffer en memoire Python.
Depuis la version 1.3.7, XGetImage s'execute dans un processus de capture dedie avec son propre Display X11. Les
diagnostics indiquent le numero de frame, la methode de capture, la resolution, l'etat du Display, le stride et la
derniere action distante. Le lanceur effectue une unique relance de secours si l'agent principal subit un arret fatal.
Depuis la version 1.3.8, l'URL temporaire est copiee automatiquement dans le presse-papiers au demarrage. Sous X11,
le controleur d'entree conserve la selection CLIPBOARD pendant toute la session afin que le lien reste disponible.
Depuis la version 1.3.9, plusieurs navigateurs peuvent controler le meme lien et un redemarrage recuperable reprend la session locale.

Aucun service systeme ni demarrage automatique n'est installe. Un arret volontaire revoque le lien. En cas de crash
recuperable ou de coupure reseau, les identifiants locaux permettent de reprendre la meme session tant que son TTL glissant reste valide.


Depuis la version 1.4.0, le client tente en priorite une liaison WebRTC P2P directe avec le navigateur. Les dependances
Python WebRTC sont installees localement dans le dossier du client via pip, sans droits administrateur. Si cette
installation, STUN/TURN ou la negociation P2P echoue, le relais HTTP existant reste actif automatiquement. Les
commandes P2P sont acceptees uniquement pour le controleur qui possede le bail exclusif attribue par le serveur.

Le protocole expose uniquement la capture d'ecran et des operations souris/clavier definies. Il ne permet
pas l'execution arbitraire de commandes distantes.

Le fichier start.sh sert de bootstrap stable. Les mises a jour remplacent atomiquement les fichiers du client
quand cela est possible, conservent les fichiers locaux absents du package et utilisent un verrou pour eviter
deux mises a jour concurrentes.