Identificadores

Usa esta página para leer un identificador de OpenLatch: qué nombra, cómo se construye, dónde aparece y qué cambios en una máquina le dan uno nuevo.

Hosts, agentes, sesiones y eventos

Por debajo de tu organización, OpenLatch conoce tres entidades y los eventos que producen. Cada una tiene un solo identificador, con un solo nombre y un solo formato dondequiera que aparezca: en la consola, en la API REST pública, en los eventos que envía el cliente y en la salida del cliente.

Entidad	Prefijo	Qué nombra	Cómo se construye
Host	hst_	Un sistema operativo de tu organización, una vida de contenedor o un clon de una imagen de máquina. Los hosts son lo que cuenta tu licencia	Derivado en la máquina a partir de su identificador de sistema operativo, o elegido al azar cuando no hay ninguno fiable
Agente	agt_	Un producto de agente, como Claude Code o Codex CLI, que usa un usuario del sistema operativo en un host, y cada perfil registrado en él. Las sesiones en paralelo en un mismo perfil siguen siendo un solo agente	Derivado de la organización, el host y el producto de agente, más un identificador de instancia para cada usuario distinto del primero del host y para un perfil registrado, así que el cliente y la plataforma calculan el mismo valor
Sesión	ses_	Una conversación de un agente	Derivado del agente y del identificador de sesión que dio el propio agente
Evento	evt_	Un evento que envía el cliente	Elegido al azar por el cliente. La plataforma guarda un evento una sola vez por identificador

Cada agente obtiene las políticas de su propia Autonomy Zone, así que dos agentes de un mismo host pueden estar en zonas distintas y cada uno se decide con la suya.

Agentes en una máquina compartida

El primer usuario del sistema operativo que envía datos desde un host conserva el Agent ID que tenía, en su perfil predeterminado, y cualquier cliente anterior sigue funcionando en ese agente. Cada otro usuario del host, y cada perfil registrado, obtiene un Agent ID propio.

Regla	Detalle
Identificador de instancia	Los eventos de un agente así llevan un atributo olinstance: un seudónimo derivado del usuario del sistema operativo y, para un perfil, de su directorio. No contiene ningún nombre ni ninguna ruta, pero se calcula con una constante incluida en cada cliente, así que no está anonimizado. Se envía también con la captura de señales de identidad desactivada
Comprobación	La plataforma vuelve a derivar el Agent ID a partir del atributo y rechaza una solicitud cuyo Agent ID no coincide, o que designa a otro usuario que el de su credencial de host, con HOST_MISMATCH
Quién es el primero	La plataforma decide una sola vez qué usuario es el primero del host, y la respuesta no cambia nunca. Hasta que el cliente tiene esa respuesta, sus eventos se quedan en el agente predeterminado, y openlatch doctor lo muestra pendiente con OL-1257
Sin nombre de usuario	Un cliente que no puede leer ningún nombre de usuario del sistema operativo se queda en el agente predeterminado, y openlatch doctor lo indica con OL-1305
Variable de prueba	OPENLATCH_TEST_OS_USER sustituye al usuario del sistema operativo, y con él al agente y a su zona. openlatch doctor lo indica siempre que está definida, con OL-1306

Formato

Cada identificador es un prefijo de tres letras, un guion bajo y 26 caracteres en base32 en minúsculas: los dígitos y las letras distintas de i, l, o y u. El prefijo dice qué nombra el identificador.

agt_01jbz3q7x2k9m4n5p6r7s8t9v0

Regla	Detalle
Visualización	La consola muestra un identificador completo, o acortado a su prefijo y sus ocho primeros caracteres; su botón de copia siempre copia el valor completo
Un identificador mal formado	Una solicitud que pasa un identificador con el prefijo equivocado para su campo, la longitud equivocada o un carácter fuera del alfabeto se rechaza con INVALID_ID, que nombra el campo
Un identificador desconocido	Un identificador bien formado que no existe, o que pertenece a otra organización, recibe la misma respuesta de no encontrado en ambos casos
No es un secreto	Los identificadores de host, agente y sesión se calculan a partir de lo que nombran, así que nunca son credenciales. Una clave de API es un secreto: empieza por openlatch_ o, en el formato más reciente, por olk_, y la plataforma acepta ambos

Dónde aparece cada identificador

Entidad	Campo en la API REST pública	Atributo de un evento que envía el cliente
Host	host_id	hostid
Agente	agent_id	agentid
Sesión	session_id	subject
Evento	event_id	id

La consola llama a los identificadores de host y de agente Host ID y Agent ID.

El producto de agente es platform en la API REST pública, por ejemplo claude-code o codex-cli, y la agrupación que tu organización da a un agente es su category. En la API REST pública, cuando un campo contiene un identificador que dio el propio agente, su nombre lo dice: native_session_id es el identificador de sesión propio del agente. Tu organización nunca aparece en un evento: la plataforma la toma de la credencial que envió el evento.

Qué da a un host un identificador nuevo

Un host conserva su identificador mientras su sistema operativo y su organización sigan siendo los mismos. Estos cambios en una máquina deciden si conserva su host, y sus agentes y sesiones siguen a su host.

Cambio	Host	Historial en la consola
Desinstalar y volver a instalar	El mismo	Continuo
Desinstalar con --purge y volver a instalar	El mismo en una máquina con identificador de sistema operativo; nuevo en un host cuyo identificador se eligió al azar	Continuo cuando el host sigue siendo el mismo; si no, queda bajo el host anterior
Sistema operativo reinstalado, o un identificador de máquina nuevo	Nuevo	Queda bajo el host anterior
Cambio a otra organización	Un host por organización; volver a una organización reutiliza su host	Cada organización conserva el suyo
Clon de una imagen de máquina preparada	Nuevo para cada clon, en su primer arranque	Cada clon empieza vacío
Clon de una imagen de máquina sin preparar	Compartido con el original hasta que los dos se ejecutan a la vez; el más reciente recibe entonces un host nuevo, y el host muestra Possible duplicate durante un tiempo	El original lo conserva; el clon empieza vacío
Contenedor que no conserva un directorio de estado	Nuevo cada vez que arranca el contenedor	Cada arranque empieza vacío

Prepara una máquina antes de capturarla como imagen con openlatch system prepare-image; consulta Desplegar el cliente. Dentro de un contenedor el cliente ignora el identificador de la máquina, porque una imagen puede llevar uno incorporado. Toolbx, Distrobox, Flatpak y el Subsistema de Windows para Linux comparten el identificador de la máquina y cuentan como la propia máquina. Una segunda instalación en la misma máquina con su propio directorio de estado, definido por OPENLATCH_DIR, recibe un host propio, y sus agentes nunca se fusionan con los de la máquina.

Un host que deja de verse deja de contar en tus hosts con licencia al cabo de 30 días, y su historial se queda en la consola; consulta Consultar licencias y uso.

Clientes más antiguos que estos identificadores

Un cliente más antiguo que la versión 0.10.0 ya no es compatible. La plataforma rechaza sus eventos con client_too_old y sus demás solicitudes con HOST_ID_REQUIRED, y sigue aplicando las políticas que ya tiene. Reinstala el cliente en esa máquina con uno de los comandos de instalación; consulta Instalar el cliente.

Cuando una máquina pasa a un cliente compatible, el cliente informa una vez de la identidad anterior de la máquina, antes de enviar ningún evento, y OpenLatch traslada los agentes de la máquina, con sus propietarios, sus zonas y su historial, a los identificadores nuevos. Hasta que ese informe se acepta, los eventos esperan en la máquina y las políticas que tiene se siguen aplicando, y openlatch doctor muestra el informe como pendiente con OL-1253.