Déployer le client

Installez le client sur chaque machine qui exécute un agent. Le client est le point de décision sur le chemin d’exécution de l’agent : l’installer connecte chaque agent déjà présent sur la machine, et dès lors chaque action couverte est décidée sur la machine, avant de s’exécuter, même quand la console est injoignable.

Avant de commencer, vérifiez ces éléments :

#	Élément	D’où il vient	Bloque
1	L’organisation existe, et les personnes qui mènent le pilote peuvent se connecter	Configurer l’organisation	Toutes les voies
2	Une clé d’API par vague de déploiement, conservée dans votre coffre de secrets	La page API Keys de votre compte	Les voies gérées uniquement
3	Au moins un agent installé sur la machine cible et connecté à son propre compte	Le programme d’installation de l’agent	Toutes les voies
4	Flux sortants approuvés, avec les réponses de modèles en flux exemptées de mise en tampon et d’inspection	Exigences réseau	Toutes les voies
5	Le type de proxy en vigueur sur le sous-réseau cible : direct, Basic, Negotiate, PAC, ou inspection TLS avec son certificat racine	L’équipe qui gère votre proxy	Les voies gérées

Un agent absent au moment de l’installation n’est pas connecté. Installez d’abord les agents, ou relancez l’installation ensuite ; la relancer est idempotent, donc une répétition n’est jamais destructrice.

Choisir une voie d’installation

Quatre voies mènent au même état final. Choisissez selon la provenance de l’identifiant et le nombre de machines que la voie doit atteindre, pas selon le système d’exploitation. La plupart des parcs en utilisent deux : le parcours développeur pour le pilote, et une voie gérée pour le reste.

Voie	Idéale pour	Portée	Identifiant
Parcours développeur	Vague 1 : une équipe pilote qui s’inscrit elle-même	Environ dix machines	Connexion par navigateur
Script de gestion des postes, contexte utilisateur	Parcs déjà gérés par Intune ou Jamf	Le parc entier	Clé de vague depuis le coffre de secrets
Gestion de configuration ou étape de pipeline	Parcs Linux et parcs mixtes dotés d’une automatisation existante, comme Ansible	Le parc entier	Clé de vague depuis une recherche dans un coffre
Image de conteneur	Machines de build et exécuteurs d’intégration continue	Une inscription par tâche	Secret d’exécution, monté par tâche

Trois commandes installent le client. Laquelle vous lancez dépend de ce que la machine possède déjà, pas de la taille du parc :

Machine	Commande
macOS ou Linux, aucun environnement d’exécution requis	Le script install.sh, ci-dessous
Windows, aucun environnement d’exécution requis	Le script install.ps1, ci-dessous
Toute machine qui dispose déjà de Node.js	npx @openlatch/client init. Node.js est ce dont npx a besoin ; le client est un binaire natif et n’a besoin d’aucun environnement d’exécution

Figure 1. Quatre voies d’installation, un seul état final : une machine inscrite avec chaque agent raccordé.

Installer une machine

Une commande inscrit une machine. Les scripts d’installation embarquent le client : la machine n’a besoin d’aucun environnement d’exécution. Lancez la ligne de la plateforme devant vous.

Sur macOS et Linux :

curl -LsSf https://openlatch.ai/install.sh | sh

Sur Windows :

powershell -ExecutionPolicy Bypass -c "irm https://openlatch.ai/install.ps1 | iex"

Sur une machine qui dispose déjà de Node.js :

npx @openlatch/client init

Les trois mènent au même état final : une équipe qui utilise déjà l’une d’elles la garde. Les scripts installent le client dans le répertoire personnel de l’utilisateur, ajoutent ce répertoire au PATH, et préviennent que le shell en cours ne le verra qu’après redémarrage. Ils lancent ensuite openlatch init par son chemin complet, pour que l’inscription se termine dans la même exécution. Si votre parc n’atteint pas le registre public de paquets, OPENLATCH_NPM_REGISTRY pointe le script et le client vers votre miroir.

Ce que fait l’installation

Étape	Ce qui se passe	Résultat attendu
Vérifier la route de sortie	La vérification des flux sortants passe en premier : une route bloquée échoue avant toute modification de la machine. Rien n’est laissé à moitié installé	La route de sortie est indiquée, avec la source qui l’a définie
Connecter chaque agent	Chaque agent installé sur la machine est connecté, selon la convention de configuration propre à cet agent. Le contenu existant de ces fichiers est préservé	Une ligne par agent trouvé, et une ligne explicite quand aucun n’est trouvé
S’authentifier	L’ordre est OPENLATCH_API_KEY dans l’environnement, puis un identifiant déjà présent dans le magasin d’identifiants du système, puis la connexion par navigateur. Une erreur réseau conserve un identifiant enregistré ; seul un refus déclenche une nouvelle connexion. Avec plusieurs organisations, la connexion demande laquelle, sauf si --org ou OPENLATCH_ORG la nomme. Sans personne à qui demander et sans identifiant, init ne lance jamais de connexion dans le navigateur et s’arrête sur OL-1600	Le compte et l’organisation sont affichés, ou une fenêtre de navigateur s’ouvre dans un terminal interactif
Interroger sur la télémétrie produit	La télémétrie est activée par défaut et peut être refusée ; le choix est proposé avant toute écriture de configuration d’agent. Elle porte des noms de commandes, des durées et des informations d’erreur, jamais de contenu	Une seule question, et le choix dans le rapport final
Démarrer avec la session de l’utilisateur	Le client s’enregistre auprès du gestionnaire de services du système d’exploitation, au niveau de l’utilisateur. Un échec ici n’est pas fatal : une session sans interface et un planificateur restreint sont tous deux surmontables	Le rapport indique que le client redémarrera après une déconnexion ou un redémarrage
Prouver, puis rendre compte	L’installation confirme que le client tourne, que chaque agent connecté répond et que la console est joignable	Un rapport final qui nomme tout ce qui demande attention, avec le remède à côté

Note

Certains agents demandent au développeur de confirmer la connexion une fois, au premier lancement après l’installation. D’ici là, l’agent est connecté sur le papier mais pas dans les faits. openlatch status montre quels agents attendent encore, et Niveaux de contrôle explique comment chaque agent reçoit un verdict. Une machine n’est pas terminée tant que le développeur n’a pas ouvert l’agent une fois.

Confirmer l’installation

openlatch status
openlatch doctor

Une machine est installée quand openlatch doctor ne signale aucun problème et que la machine apparaît dans le registre des agents de la console avec ses agents et un propriétaire. Vérifier et déployer couvre cette vérification machine par machine et sur une vague entière.

Derrière un proxy d’entreprise

Chaque appel sortant du client emprunte une seule route de sortie. Le trafic de bouclage sur la machine ne l’emprunte jamais. La route est résolue réglage par réglage : une option peut fixer l’URL du proxy pendant que le paquet de certificats vient d’ailleurs.

Rang	Source	À utiliser pour
1	Les options de la commande openlatch init	Fixer la route au moment de l’inscription
2	OPENLATCH_PROXY et ses variables sœurs	Le seul canal autorisé à porter un identifiant de proxy
3	La configuration propre du client, écrite à l’installation	Ce que le client lit quand il démarre avec la session, là où aucune variable de shell n’existe
4	La famille standard de variables https_proxy	Un parc qui les exporte déjà pour tous les outils
5	La découverte par le système d’exploitation	Une inscription sans configuration sur un poste géré
6	Direct	Le dernier recours. Il peut être refusé, pour qu’une route non résolue échoue au lieu de passer en direct

Ce qui a permis l’installation est écrit dans la configuration propre du client, avec sa source. Le client démarre avec la session de l’utilisateur et n’hérite d’aucune variable du shell d’installation : une route qui n’existait que dans une variable d’environnement laisserait la machine passer en direct après la fin de la session.

openlatch init --proxy http://proxy.corp:8080 --ca-bundle /etc/ssl/corp-root.pem
openlatch init --proxy http://proxy.corp:8080 --proxy-auth negotiate --proxy-spn HTTP/proxy.corp

Le paquet de certificats est fusionné par-dessus le magasin de confiance du système, sans jamais le remplacer, et la vérification n’est jamais désactivée. Negotiate utilise l’identité de la session ouverte, avec un nom de principal de service qui vaut par défaut HTTP/ suivi de l’hôte du proxy. NTLM est refusé par choix de conception : un parc uniquement NTLM demande un changement côté proxy avant l’inscription.

Un identifiant passé dans --proxy est refusé, car les arguments de ligne de commande sont lisibles par tous les processus de l’hôte. Fournissez-le par OPENLATCH_PROXY ou répondez à la question dans un terminal. Dans les deux cas, le mot de passe va dans le magasin d’identifiants du système, n’atterrit jamais dans un fichier sur disque, et est masqué dans chaque ligne de journal.

Attention

Sur un hôte derrière un proxy, les adresses de bouclage doivent figurer dans la liste d’exceptions du proxy du shell qui lance vos agents. Certains agents reçoivent cette entrée automatiquement à l’installation. Quand un agent n’a aucun endroit pour la recevoir, exportez NO_PROXY=127.0.0.1,localhost dans le shell qui le lance. Sans cela, le trafic de l’agent vers le client part vers le proxy d’entreprise au lieu de rester sur la machine, et le proxy répond par une erreur.

Installations gérées pour les parcs

Attention

Utilisez une clé d’API par vague de déploiement, lue depuis votre coffre de secrets et révoquée dans la console quand la vague se termine. N’écrivez jamais la clé dans un script, un paquet ou une ligne de commande. Chaque exemple ci-dessous place OPENLATCH_API_KEY dans l’environnement de l’installation. Quand la plateforme de gestion peut transmettre une valeur à un script, comme Jamf avec le paramètre 4, utilisez ce canal ; quand elle ne le peut pas, comme Intune, le script va chercher la clé dans le coffre de secrets en première action. Considérez le corps d’un script de déploiement comme lisible : une plateforme de gestion le conserve en clair et peut l’écrire dans les journaux de l’appareil.

Une installation gérée lance le même script avec trois ajouts :

Ajout	Effet
OPENLATCH_INSTALL_YES	Rend l’installation non interactive
OPENLATCH_NO_INIT	Retient l’inscription que le script lancerait sinon à la fin, pour que votre script lance lui-même openlatch init --yes. Avec --yes, l’inscription ne pose jamais de question : elle échoue et nomme ce qui lui manquait
OPENLATCH_API_KEY dans l’environnement	L’identifiant arrive depuis votre coffre de secrets plutôt que par un navigateur

Lancez openlatch doctor en dernière ligne de chaque script et collectez sa sortie : une machine installée mais pas entièrement connectée reste ainsi visible au lieu d’être comptée comme terminée.

Script de gestion des postes, contexte utilisateur (Windows)

# Platform script, user context. Runs silently and cannot prompt.
$ErrorActionPreference = "Stop"

# The platform has no field that sets an environment variable, so the script
# fetches the wave key itself, as its first action. Replace this call with the
# one your secret store provides.
$env:OPENLATCH_API_KEY = Get-WaveKeyFromSecretStore
if (-not $env:OPENLATCH_API_KEY) {
  Write-Output "the wave key could not be read from the secret store"; exit 1
}

$env:OPENLATCH_INSTALL_YES = "1"
$env:OPENLATCH_NO_INIT     = "1"

powershell -ExecutionPolicy Bypass -c "irm https://openlatch.ai/install.ps1 | iex"
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

$openlatch = "$env:LOCALAPPDATA\openlatch\bin\openlatch.exe"
& $openlatch init --yes
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
& $openlatch doctor
exit $LASTEXITCODE

Intune exécute les scripts en silence et ne prend pas en charge l’installation interactive : c’est pourquoi l’installation est non interactive et --yes est obligatoire. L’extension de gestion récupère les affectations selon son propre calendrier : prévoyez une vague en jours plutôt qu’en minutes. Un script en contexte utilisateur demande un utilisateur connecté, et les scripts de plateforme n’atteignent pas les appareils seulement inscrits auprès de Microsoft Entra ID ; pour atteindre les appareils personnels inscrits, utilisez la voie d’application Win32 avec un comportement d’installation User, que l’absence d’élévation rend possible.

Aucun réglage Intune ne définit de variable d’environnement pour un script de plateforme. C’est pourquoi l’appel au coffre de secrets est la première action du script. Passer la clé en argument n’est pas une option : le client refuse un identifiant dans ses propres arguments.

Script de gestion des postes, contexte utilisateur (macOS)

Jamf transmet sa première valeur personnalisée dans le paramètre 4, ce qui garde la clé hors du corps du script. La règle n’a besoin d’aucune étape de création de paquet, car l’installation s’enregistre dans le répertoire personnel de l’utilisateur. Associez la règle à un déclencheur au niveau de l’utilisateur pour que l’inscription s’exécute en tant que développeur et non en tant que root.

#!/bin/zsh
set -eu

# Parameter 4 carries the wave key, or replace this line with a secret-store call.
export OPENLATCH_API_KEY="${4:?wave key was not supplied}"

export OPENLATCH_INSTALL_YES=1
export OPENLATCH_NO_INIT=1

curl -LsSf https://openlatch.ai/install.sh | sh

"$HOME/.local/bin/openlatch" init --yes
"$HOME/.local/bin/openlatch" doctor

Gestion de configuration ou étape de pipeline

- name: Install the OpenLatch client
  ansible.builtin.shell: curl -LsSf https://openlatch.ai/install.sh | sh
  args:
    creates: "{{ ansible_env.HOME }}/.local/bin/openlatch"
  environment:
    OPENLATCH_INSTALL_YES: "1"
    OPENLATCH_NO_INIT: "1"

- name: Enroll the machine
  ansible.builtin.command: "{{ ansible_env.HOME }}/.local/bin/openlatch init --yes"
  environment:
    # Or a vault lookup, so the value never lands in the play or in a fact.
    OPENLATCH_API_KEY: "{{ lookup('env', 'OPENLATCH_API_KEY') }}"

- name: Report what the machine looks like
  ansible.builtin.command: "{{ ansible_env.HOME }}/.local/bin/openlatch doctor"
  changed_when: false

Lancez l’inscription sur un échantillon de la vague avant l’exécution complète, et lisez la sortie de la tâche de rapport sur ces machines. Un type de proxy que l’installation ne sait pas découvrir apparaît là, plutôt que sur toutes les machines à la fois.

Image de conteneur et intégration continue

FROM debian:bookworm-slim
RUN apt-get update \
 && apt-get install -y --no-install-recommends ca-certificates curl \
 && rm -rf /var/lib/apt/lists/*

ENV OPENLATCH_INSTALL_YES=1 \
    OPENLATCH_NO_INIT=1 \
    OPENLATCH_NO_MODIFY_PATH=1 \
    OPENLATCH_INSTALL_DIR=/usr/local/bin

RUN curl -LsSf https://openlatch.ai/install.sh | sh
COPY entrypoint.sh /usr/local/bin/entrypoint.sh
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

entrypoint.sh

#!/bin/sh
set -eu
: "${OPENLATCH_API_KEY:?the runtime secret was not mounted}"
openlatch init --yes --no-persistence
exec "$@"

- name: Enroll the runner
  env:
    OPENLATCH_API_KEY: ${{ secrets.OPENLATCH_API_KEY }}
    OPENLATCH_INSTALL_YES: "1"
    OPENLATCH_NO_INIT: "1"
  run: |
    curl -LsSf https://openlatch.ai/install.sh | sh
    "$HOME/.local/bin/openlatch" init --yes --no-persistence
    "$HOME/.local/bin/openlatch" status

L’image de base n’embarque rien pour le client : le script apporte le client avec lui. L’identifiant est monté à l’exécution, donc aucune couche de l’image ne le contient. OPENLATCH_NO_MODIFY_PATH empêche l’installation d’écrire une ligne PATH dans un profil de shell qu’aucun shell interactif ne lira, et OPENLATCH_INSTALL_DIR place le client là où le PATH de l’image cherche déjà. --no-persistence ignore le gestionnaire de services, car un conteneur n’a pas de session utilisateur dans laquelle démarrer. La télémétrie produit est désactivée en intégration continue sans configuration. Les exécuteurs éphémères s’inscrivent à chaque tâche, et comme une installation répétée est sans risque, une tâche relancée l’est aussi.

Ce que le client installe sur une machine

Le client s’installe et s’exécute au niveau de l’utilisateur. Aucun droit d’administrateur n’est requis, rien n’est écrit dans un répertoire système, et aucun service n’est enregistré au niveau de la machine.

Élément	Détail
Une seule unité installée	Le client OpenLatch, installé une fois par machine qui exécute un agent
Où il arrive	Les scripts placent le client dans ~/.local/bin sur macOS et Linux, et dans %LOCALAPPDATA%\openlatch\bin sur Windows, puis ajoutent ce répertoire au PATH. OPENLATCH_INSTALL_DIR le déplace. Ce n’est volontairement pas le répertoire d’état ci-dessous
Fichiers	Le client conserve sa configuration et ses enregistrements locaux dans un seul répertoire : ~/.openlatch sur macOS et Linux, %APPDATA%\openlatch sur Windows. OPENLATCH_DIR le déplace. Tout élément sensible qu’il contient n’est lisible que par son propriétaire
Configuration des agents	Le fichier de configuration de chaque agent connecté reçoit une entrée qui pointe vers le client. Le contenu existant est préservé, et l’état antérieur est enregistré pour pouvoir être restauré
Démarrage	Le client démarre avec la session de l’utilisateur, sous le gestionnaire de services du système d’exploitation
Identifiants	La clé d’API, et tout identifiant de proxy, sont conservés dans le magasin d’identifiants du système
Posture réseau	N’écoute que sur l’interface de bouclage. Aucun port entrant n’est ouvert

openlatch uninstall déconnecte chaque agent trouvé sur la machine, arrête le client, et restaure ce qu’il avait modifié dans la configuration de chaque agent. openlatch uninstall --purge supprime aussi le répertoire d’état et l’identifiant enregistré. Une purge ne supprime pas les fichiers installés : ils se trouvent hors du répertoire d’état, si bien qu’une purge les laisse, ainsi que la ligne PATH ajoutée par le script. Exploiter couvre la suppression complète.

En bref

• Quatre voies d’installation mènent à un seul état final. Choisissez selon la provenance de l’identifiant et le nombre de machines à atteindre, pas selon le système d’exploitation.
• Les scripts d’installation inscrivent une machine sur macOS, Windows et Linux sans aucun environnement d’exécution ; npx @openlatch/client init mène au même état final là où Node.js est présent. Dans tous les cas, l’installation détecte les agents présents et connecte chacun d’eux, et la relancer est sans risque.
• Certains agents demandent au développeur de confirmer la connexion une fois. Une machine n’est pas terminée tant que ce n’est pas fait.
• Une machine est installée quand openlatch doctor ne signale aucun problème et que la machine apparaît dans le registre des agents de la console avec ses agents et un propriétaire.
• Une clé d’API par vague, lue depuis votre coffre de secrets à l’exécution, jamais dans un script, un paquet ou une ligne de commande.