1dabb5110f
docs(help): bring the user guide back in line with the current app The help was written on 2026-10-14 and about forty user-visible changes merged since without touching it, so several pages described controls that no longer exist: Missions still listed four playbooks and a Save step for preferences that now save on each change, the depth editor kept its old names, notifications still had their former switches, and voice input pointed to a microphone button that is not in the composer. Every English page was re-checked claim by claim against the current labels (English UI messages) and behaviour, then the nine translations were updated to match, using each locale's own UI labels. Notable corrections: Missions (Compare two models, autosaving defaults with Apply to / Global / Reset, Subsession nesting depth, prepared hand-offs, retired-task interrupts, the named causes of "Mission Control is unavailable", standalone server support); conversations and history (reasoning/tool durations, token lines adding up the cleanup selection, presets including Nothing, timeline markers following Message content, in-place reveal of long text, Open in session, focus after send, Queue message / Steer now, Retrying); settings (notification routing table and defaults, Stats, Mode, info tips, Server setting badge, localized native menus); shortcuts (72 actions, Clear shortcut, Ctrl/Cmd+K); voice (More actions entries, Save status); files (live Workspace refresh, Show 200 more); OpenCode, install, server and updates (2.1.1 recommended, OpenCode 2 beside an older installation, version card first, private loopback listener for Missions, preview releases offered once all builds are published); providers, integrations, browser, SideCars, desktop and remote pages. Translations also repaired older drift, mainly the project-tab closing passages. The Chat settings table header (Default state, its title, item column, the thinking row and its accessible label) was still English in eight locales; it is now translated so the help can cite what users see. AGENTS.md now asks every PR changing user-visible behavior to update the affected help pages in the same PR, since CI validates structure and links but not whether the text still matches the UI; it also corrects the needs-input notification default. USER_HELP.md no longer claims native menus stay English. Validation: npm run test:help (all ten locales, 25 pages, heading ids unchanged), a full help build, and the i18n and transcript-visibility unit tests.
9.8 KiB
Accès distant direct
L’accès direct se connecte aux écoutes HTTP/HTTPS de CodeNomad avec son mot de passe serveur. Il est distinct du Contrôle à distance : l’appairage ne nécessite ni écoute LAN ni port entrant, et aucun chemin ne bascule silencieusement vers l’autre.
Choisir un chemin d’accès
| Chemin | Ce que vous administrez |
|---|---|
| Navigateur sur la même machine | Gardez l’écoute en boucle locale ; utilisez l’URL locale affichée. |
| LAN ou VPN | Écoutez sur une interface accessible, limitez le pare-feu aux clients voulus et utilisez un HTTPS de confiance. Un VPN ne configure pas l’écoute CodeNomad à votre place. |
| Transfert SSH | Gardez le backend en boucle locale ; transférez son port réellement affiché. Le tunnel protège le transport mais ne remplace pas l’authentification CodeNomad. |
| Proxy inverse | Gardez le backend sur une interface privée/de boucle locale ; terminez le TLS de confiance au proxy, protégez le saut amont et prenez en charge les SSE de longue durée ainsi que les WebSockets nécessaires aux outils d’accès direct. |
| Contrôle à distance | Appairez l’appareil depuis l’hôte ; voir Contrôle à distance pour sa surface plus restreinte et sa durée de vie. |
L’adresse d’écoute ne crée pas de règles de pare-feu, transfert de ports, DNS ou VPN. Ne publiez pas une écoute HTTP non authentifiée sur Internet. Une racine d’espace de travail n’est pas un bac à sable de sécurité ; lisez Sécurité avant d’exposer le serveur.
Activer l’accès direct
- Sur l’hôte, ouvrez Paramètres → Accès distant et développez Accès direct (réseau local, avancé).
- Sous Mot de passe du serveur, choisissez Définir le mot de passe ou Changer le mot de passe, saisissez Nouveau mot de passe et Confirmer le mot de passe, puis Enregistrer le mot de passe. Les mots de passe fournis à l’exécution ne se changent pas ici ; voir Sécurité.
- Activez Autoriser les connexions depuis d'autres IP sous Mode d'écoute. Lisez l’avertissement et choisissez Redémarrer maintenant seulement lorsque vous êtes prêt pour l’interruption temporaire.
- Après redémarrage, utilisez Rafraîchir et vérifiez Adresses accessibles. Ouvrez l’adresse HTTPS accessible sur l’autre appareil, ou choisissez Afficher le QR sur l’hôte et scannez-le avec l’autre appareil, puis connectez-vous.
Cela change le mode d’écoute directe de l’hôte, pas un projet ni le Contrôle à distance. La section s’ouvre automatiquement tant que le serveur écoute au-delà de localhost. Si le redémarrage automatique est indisponible, redémarrez CodeNomad manuellement ; les déploiements autonomes doivent régler leur --host de lancement de manière cohérente. Pour retirer l’exposition, désactivez le commutateur et redémarrez, ou relancez la CLI en boucle locale. Cela ne révoque pas les appareils appairés au Contrôle à distance.
Matrice des adresses d’écoute
--host vaut 127.0.0.1 par défaut ; localhost est normalisé vers cette adresse. Les règles suivantes s’appliquent aux écoutes activées :
| Lancement/mode | HTTP écoute sur | HTTPS écoute sur |
|---|---|---|
| Autonome, HTTPS seul (défaut) | Écoute privée en boucle locale uniquement (voir ci-dessous) | --host |
| Autonome, HTTP seul | --host, y compris une adresse LAN/générique |
Non activé |
| Autonome, les deux écoutes | 127.0.0.1 quel que soit --host |
--host |
| Backend de bureau natif | Son écoute HTTP reste sur 127.0.0.1, y compris son écoute interne à l’hôte |
--host quand HTTPS est activé |
Chaque backend conserve aussi une écoute HTTP sur 127.0.0.1 pour les plugins OpenCode fournis avec CodeNomad, comme Missions. Lorsque HTTP n’a pas été demandé, ou que l’écoute HTTP demandée est liée à une autre adresse que 127.0.0.1 ou 0.0.0.0, le backend ajoute une écoute HTTP privée sur un port aléatoire de 127.0.0.1. Elle n’est jamais affichée ni proposée comme adresse de connexion, n’est pas accessible depuis d’autres machines et sert la même application authentifiée.
Une adresse LAN précise n’accepte pas nécessairement les connexions de boucle locale. 0.0.0.0 désigne toutes les interfaces IPv4 ; :: est l’écoute générique double pile. Utilisez une adresse réellement accessible dans un navigateur, pas une adresse générique. Les identifiants de zone IPv6 ne sont pas pris en charge dans --host.
Pour un déploiement HTTPS autonome, définissez un mot de passe par la procédure d’initialisation, puis exécutez :
codenomad --host 0.0.0.0 --https=true --http=false
Pour du HTTP en boucle locale uniquement, par exemple derrière un proxy local de confiance :
codenomad --host 127.0.0.1 --https=false --http=true
Ne supposez pas le port 9898 ou 9899 : les ports omis peuvent changer s’ils sont occupés. Un --https-port explicite non nul, ou un --http-port avec HTTP activé, fixe le port et échoue si l’écoute est impossible ; 0 demande au système d’en attribuer un. Les Local Connection URL et Remote Connection URL affichées, et les Adresses accessibles actualisées, font autorité pour cette exécution. Voir la référence CLI serveur complète.
Configurer un TLS de confiance
Fournir son propre certificat
- Obtenez un certificat dont les noms alternatifs du sujet (SAN) couvrent le nom d’hôte ou l’IP réellement utilisés par les clients.
- Fournissez à la fois
--tls-key <path>et--tls-cert <path>comme fichiers PEM. Ajoutez--tls-ca <path>si votre déploiement nécessite une chaîne/un ensemble d’AC. - Redémarrez CodeNomad et vérifiez le certificat et l’adresse HTTPS affichée depuis l’appareil client.
Les fichiers de certificat personnalisés sont lus au démarrage et jamais réécrits par CodeNomad. Vous gérez leur renouvellement et le redémarrage nécessaire au chargement des fichiers renouvelés. --tlsSANs configure les certificats générés ; il ne peut pas ajouter des noms à un certificat fourni. Protégez les clés privées et ne faites confiance qu’aux certificats dont vous avez vérifié l’identité d’hôte.
Utiliser l’AC locale générée
Avec HTTPS activé et sans paire clé/certificat fournie, CodeNomad crée une AC locale et un certificat serveur sous la base de configuration :
| Fichier | Utilité |
|---|---|
tls/ca-cert.pem |
Certificat public d’AC à distribuer de façon sûre aux clients que vous administrez. |
tls/ca-key.pem |
Clé privée d’AC ; ne jamais distribuer. |
tls/server-cert.pem |
Certificat serveur. |
tls/server-key.pem |
Clé privée serveur ; ne jamais distribuer. |
- Ajoutez chaque nom DNS/IP visible des clients avec
--tlsSANs "host.example.test,192.0.2.10". Une écoute générique ne découvre pas toutes vos adresses LAN pour les SAN. - Redémarrez le backend pour générer/revérifier le certificat.
- Vérifiez l’hôte/l’AC par un canal de confiance, puis importez uniquement le certificat d’AC dans chaque magasin de confiance client/navigateur voulu. Sinon, utilisez un certificat reconnu publiquement ou un proxy inverse TLS.
Le certificat serveur généré dure 30 jours. Le démarrage le renouvelle à moins de trois jours de l’expiration, si des SAN requis manquent, s’il échoue aux contrôles ou si son fichier de clé privée manque. L’AC générée dure 365 jours et est remplacée lorsqu’elle expire, échoue aux contrôles ou que son fichier de clé privée manque ; cela réémet aussi le certificat serveur. Les clés privées existantes corrompues, illisibles ou incompatibles ne sont pas réparées automatiquement. Les clients doivent faire confiance à l’AC de remplacement. Aucun renouvellement continu n’a lieu dans le processus : prévoyez un redémarrage délibéré avant expiration pour les déploiements de longue durée.
Si un client signale un avertissement de certificat, arrêtez-vous et vérifiez le nom d’hôte, les SAN, le magasin de confiance et l’expiration. Ne désactivez pas la vérification et ne faites pas du contournement des avertissements votre procédure de déploiement. Un HTTPS de confiance est aussi requis pour des fonctions de navigateur distant telles que l’installation PWA et l’accès au microphone.
Enregistrer un serveur distant
- Sur l’accueil de bureau, choisissez Se connecter au serveur CodeNomad. Le même bouton apparaît dans un onglet Serveurs vide et dans Paramètres → Accès distant → Serveurs.
- Dans Se connecter à un serveur, saisissez Nom du serveur et URL du serveur avec une origine HTTPS de confiance. Laissez Ignorer la vérification TLS pour les certificats auto-signés. décoché ; établissez plutôt la confiance.
- Choisissez Enregistrer pour ajouter un favori, ou Se connecter pour l’enregistrer et l’ouvrir. Connectez-vous sur ce serveur.
Sélectionnez un serveur enregistré dans l’onglet Serveurs de l’accueil pour l’ouvrir de nouveau. Les favoris appartiennent à cette configuration CodeNomad, pas aux projets du serveur distant. Enregistrer une URL ne démarre pas le serveur et n’accorde pas l’accès. Supprimer le serveur enregistré retire le favori, pas les conversations distantes, le backend ou ses identifiants.
Pour le Contrôle à distance, collez plutôt un lien d’appairage récent dans URL du serveur. Le favori ne conserve que l’origine du tunnel, jamais le code d’appairage à usage unique ; voir Contrôle à distance pour le réappairage après perte du cookie de l’appareil.