Identifiants

Utilisez cette page pour lire un identifiant OpenLatch : ce qu’il nomme, comment il est construit, où il apparaît, et quels changements d’une machine lui en donnent un nouveau.

Hôtes, agents, sessions et événements

Sous votre organisation, OpenLatch connaît trois entités et les événements qu’elles produisent. Chacune a un seul identifiant, avec un seul nom et un seul format partout où il apparaît : dans la console, dans l’API REST publique, dans les événements que le client envoie et dans la sortie du client.

Entité	Préfixe	Ce qu’il nomme	Comment il est construit
Hôte	hst_	Un système d’exploitation de votre organisation, une vie de conteneur, ou un clone d’une image de machine. Ce sont les hôtes que compte votre licence	Dérivé sur la machine à partir de son identifiant de système d’exploitation, ou tiré au hasard quand il n’y en a aucun de fiable
Agent	agt_	Un produit d’agent, tel que Claude Code ou Codex CLI, utilisé par un utilisateur du système d’exploitation sur un hôte, et chaque profil qui y est enregistré. Les sessions en parallèle dans un même profil restent un seul agent	Dérivé de l’organisation, de l’hôte et du produit d’agent, plus un identifiant d’instance pour chaque utilisateur autre que le premier de l’hôte et pour un profil enregistré, si bien que le client et la plateforme calculent la même valeur
Session	ses_	Une conversation d’un agent	Dérivé de l’agent et de l’identifiant de session que l’agent lui-même a donné
Événement	evt_	Un événement que le client envoie	Tiré au hasard par le client. La plateforme enregistre un événement une seule fois par identifiant

Chaque agent récupère les politiques de sa propre Autonomy Zone : deux agents d’un même hôte peuvent donc relever de zones différentes, et chacun est décidé avec la sienne.

Agents sur une machine partagée

Le premier utilisateur du système d’exploitation à remonter des données depuis un hôte garde l’Agent ID qu’il avait, dans son profil par défaut, et tout client antérieur continue de fonctionner sur cet agent. Chaque autre utilisateur de l’hôte, et chaque profil enregistré, obtient un Agent ID qui lui est propre.

Règle	Détail
Identifiant d’instance	Les événements d’un tel agent portent un attribut olinstance : un pseudonyme dérivé de l’utilisateur du système d’exploitation et, pour un profil, de son répertoire. Il ne contient ni nom ni chemin, mais il est calculé avec une constante livrée dans chaque client, il n’est donc pas anonymisé. Il est envoyé même avec la capture des signaux d’identité désactivée
Vérification	La plateforme dérive à nouveau l’Agent ID à partir de l’attribut et refuse une requête dont l’Agent ID ne correspond pas, ou qui désigne un autre utilisateur que celui de son identifiant d’hôte, avec HOST_MISMATCH
Qui est le premier	La plateforme décide une fois pour toutes quel utilisateur est le premier de l’hôte, et la réponse ne change jamais. Tant que le client n’a pas cette réponse, ses événements restent sur l’agent par défaut, et openlatch doctor l’affiche en attente avec OL-1257
Aucun nom d’utilisateur	Un client qui ne peut lire aucun nom d’utilisateur du système d’exploitation reste sur l’agent par défaut, et openlatch doctor le signale avec OL-1305
Variable de test	OPENLATCH_TEST_OS_USER remplace l’utilisateur du système d’exploitation, et donc l’agent et sa zone. openlatch doctor le signale dès qu’elle est définie, avec OL-1306

Format

Chaque identifiant est un préfixe de trois lettres, un trait de soulignement et 26 caractères en base32 minuscule : les chiffres et les lettres autres que i, l, o et u. Le préfixe dit ce que l’identifiant nomme.

agt_01jbz3q7x2k9m4n5p6r7s8t9v0

Règle	Détail
Affichage	La console montre un identifiant en entier, ou raccourci à son préfixe et à ses huit premiers caractères ; son bouton de copie copie toujours la valeur entière
Un identifiant mal formé	Une requête qui passe un identifiant avec le mauvais préfixe pour son champ, la mauvaise longueur ou un caractère hors de l’alphabet est refusée avec INVALID_ID, qui nomme le champ
Un identifiant inconnu	Un identifiant bien formé qui n’existe pas, ou qui appartient à une autre organisation, reçoit la même réponse « introuvable » dans les deux cas
Pas un secret	Les identifiants d’hôte, d’agent et de session sont calculés à partir de ce qu’ils nomment : ce ne sont jamais des identifiants de connexion. Une clé d’API est un secret : elle commence par openlatch_ ou, dans le format plus récent, par olk_, et la plateforme accepte les deux

Où chaque identifiant apparaît

Entité	Champ dans l’API REST publique	Attribut d’un événement envoyé par le client
Hôte	host_id	hostid
Agent	agent_id	agentid
Session	session_id	subject
Événement	event_id	id

La console nomme les identifiants d’hôte et d’agent Host ID et Agent ID.

Le produit d’agent est platform dans l’API REST publique, par exemple claude-code ou codex-cli, et le regroupement que votre organisation donne à un agent est sa category. Dans l’API REST publique, quand un champ contient un identifiant que l’agent lui-même a donné, son nom le dit : native_session_id est l’identifiant de session propre à l’agent. Votre organisation n’apparaît jamais dans un événement : la plateforme la déduit de l’identifiant de connexion qui a envoyé l’événement.

Ce qui donne à un hôte un nouvel identifiant

Un hôte garde son identifiant tant que son système d’exploitation et son organisation restent les mêmes. Ces changements d’une machine décident si elle garde son hôte, et ses agents et ses sessions suivent leur hôte.

Changement	Hôte	Historique dans la console
Désinstaller, puis réinstaller	Le même	Continu
Désinstaller avec --purge, puis réinstaller	Le même sur une machine qui a un identifiant de système d’exploitation ; nouveau sur un hôte dont l’identifiant a été tiré au hasard	Continu quand l’hôte reste le même ; sinon il reste sous l’ancien hôte
Système d’exploitation réinstallé, ou nouvel identifiant de machine	Nouveau	Reste sous l’ancien hôte
Passage à une autre organisation	Un hôte par organisation ; revenir à une organisation réutilise son hôte	Chaque organisation garde le sien
Clone d’une image de machine préparée	Nouveau pour chaque clone, à son premier démarrage	Chaque clone part de zéro
Clone d’une image de machine non préparée	Partagé avec l’original jusqu’à ce que les deux tournent en même temps ; le plus récent reçoit alors un nouvel hôte, et l’hôte affiche Possible duplicate pendant un moment	L’original le garde ; le clone part de zéro
Conteneur qui ne garde pas de répertoire d’état	Nouveau à chaque démarrage du conteneur	Chaque démarrage part de zéro

Préparez une machine avant de la capturer comme image avec openlatch system prepare-image ; voir Déployer le client. Dans un conteneur, le client ignore l’identifiant de la machine, car une image peut en embarquer un. Toolbx, Distrobox, Flatpak et le sous-système Windows pour Linux partagent l’identifiant de la machine et comptent comme la machine elle-même. Une seconde installation sur la même machine avec son propre répertoire d’état, défini par OPENLATCH_DIR, reçoit un hôte à elle, et ses agents ne fusionnent jamais avec ceux de la machine.

Un hôte qui n’est plus vu cesse de compter dans vos hôtes sous licence au bout de 30 jours, et son historique reste dans la console ; voir Lire les licences et l’usage.

Clients plus anciens que ces identifiants

Un client plus ancien que la version 0.10.0 n’est plus pris en charge. La plateforme refuse ses événements avec client_too_old et ses autres requêtes avec HOST_ID_REQUIRED, et il continue d’appliquer les politiques qu’il détient déjà. Réinstallez le client sur cette machine avec l’une des commandes d’installation ; voir Installer le client.

Quand une machine passe à un client pris en charge, le client signale une fois l’identité précédente de la machine, avant d’envoyer le moindre événement, et OpenLatch déplace les agents de la machine, avec leurs propriétaires, leurs zones et leur historique, vers les nouveaux identifiants. Tant que ce signalement n’est pas accepté, les événements attendent sur la machine et les politiques qu’elle détient continuent d’être appliquées, et openlatch doctor montre le signalement comme en attente avec OL-1253.