Desplegar el cliente

Instala el cliente en cada máquina que ejecuta un agente. El cliente es el punto de decisión en el camino de ejecución del agente: instalarlo conecta cada agente ya presente en la máquina, y desde entonces cada acción cubierta se decide en la máquina, antes de ejecutarse, incluso cuando la consola no es accesible.

Antes de empezar, comprueba estos elementos:

#	Elemento	De dónde viene	Bloquea
1	La organización existe, y las personas que llevan el piloto pueden iniciar sesión	Configurar la organización	Todas las rutas
2	Una clave de API por oleada de despliegue, guardada en tu almacén de secretos	La página API Keys de tu cuenta	Solo las rutas gestionadas
3	Al menos un agente instalado en la máquina de destino y con sesión iniciada en su propia cuenta	El instalador del propio agente	Todas las rutas
4	Tráfico saliente aprobado, con las respuestas de modelos en streaming exentas de almacenamiento en búfer y de inspección	Requisitos de red	Todas las rutas
5	El tipo de proxy vigente en la subred de destino: directo, Basic, Negotiate, PAC, o inspección TLS con su certificado raíz	El equipo que gestiona tu proxy	Las rutas gestionadas

Un agente ausente cuando se ejecuta la instalación no queda conectado. Instala primero los agentes, o vuelve a ejecutar la instalación después; volver a ejecutarla es idempotente, así que repetirla nunca es destructivo.

Elegir una ruta de instalación

Cuatro rutas llevan al mismo estado final. Elige según de dónde viene la credencial y a cuántas máquinas debe llegar la ruta, no según el sistema operativo. La mayoría de los entornos usan dos: la ruta de desarrollador para el piloto y una ruta gestionada para el resto.

Ruta	Ideal para	Alcance	Credencial
Ruta de desarrollador	Oleada 1: un equipo piloto que se inscribe por sí mismo	Unas diez máquinas	Inicio de sesión en el navegador
Script de gestión de equipos, contexto de usuario	Entornos ya gestionados con Intune o Jamf	Todo el parque	Clave de la oleada desde el almacén de secretos
Gestión de configuración o paso de pipeline	Parques Linux y entornos mixtos con automatización existente, como Ansible	Todo el parque	Clave de la oleada desde una consulta a un almacén
Imagen de contenedor	Máquinas de compilación y ejecutores de integración continua	Una inscripción por trabajo	Secreto de ejecución, montado por trabajo

Tres comandos instalan el cliente. Cuál ejecutas depende de lo que ya tiene la máquina, no del tamaño del parque:

Máquina	Comando
macOS o Linux, sin entorno de ejecución	El script install.sh, más abajo
Windows, sin entorno de ejecución	El script install.ps1, más abajo
Cualquier máquina que ya tenga Node.js	npx @openlatch/client init. Node.js es lo que necesita npx; el cliente es un binario nativo y no necesita ningún entorno de ejecución

Figura 1. Cuatro rutas de instalación, un único estado final: una máquina inscrita con cada agente conectado.

Instalar una máquina

Un comando inscribe una máquina. Los scripts de instalación llevan el cliente consigo, así que la máquina no necesita ningún entorno de ejecución. Ejecuta la línea de la plataforma que tienes delante.

En macOS y Linux:

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

En Windows:

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

En una máquina que ya tiene Node.js:

npx @openlatch/client init

Los tres llevan al mismo estado final, así que un equipo que ya usa uno lo conserva. Los scripts instalan el cliente en el directorio personal del usuario, añaden ese directorio al PATH y avisan de que el shell actual no lo verá hasta reiniciarse. Después ejecutan openlatch init por su ruta completa, para que la inscripción termine en la misma ejecución. Si tu entorno no llega al registro público de paquetes, OPENLATCH_NPM_REGISTRY apunta el script y el cliente a tu espejo.

Qué hace la instalación

Paso	Qué ocurre	Resultado esperado
Comprobar la ruta de salida	La comprobación del tráfico saliente va primero: una ruta bloqueada falla antes de cambiar nada en la máquina. Nada queda instalado a medias	Se indica la ruta de salida, con el origen que la definió
Conectar cada agente	Se conecta cada agente instalado en la máquina, según la convención de configuración propia de ese agente. Se conserva el contenido existente de esos archivos	Una línea por agente encontrado, y una línea explícita cuando no se encuentra ninguno
Autenticarse	El orden es OPENLATCH_API_KEY en el entorno, luego una credencial ya presente en el almacén de credenciales del sistema y, por último, el inicio de sesión en el navegador. Un error de red conserva una credencial guardada; solo un rechazo provoca un nuevo inicio de sesión. Con varias organizaciones, el inicio de sesión pregunta cuál, salvo que --org u OPENLATCH_ORG la nombre. Sin nadie a quien preguntar y sin credencial, init nunca inicia una sesión en el navegador y se detiene con OL-1600	Se muestran la cuenta y la organización, o se abre una ventana del navegador en un terminal interactivo
Preguntar por la telemetría de producto	La telemetría está activada por defecto y se puede rechazar; la elección se ofrece antes de escribir ninguna configuración de agente. Contiene nombres de comandos, duraciones e información de errores, nunca contenido	Una sola pregunta, y la elección en el informe final
Arrancar con la sesión del usuario	El cliente se registra en el gestor de servicios del sistema operativo, a nivel de usuario. Un fallo aquí no es fatal: una sesión sin interfaz y un planificador restringido se pueden superar	El informe indica que el cliente volverá a arrancar tras cerrar sesión o reiniciar
Demostrarlo e informar	La instalación confirma que el cliente se está ejecutando, que cada agente conectado responde y que se llega a la consola	Un informe final que nombra todo lo que requiere atención, con la solución al lado

Nota

Algunos agentes piden al desarrollador que confirme la conexión una vez, la primera vez que se ejecutan tras la instalación. Hasta entonces, el agente está conectado en teoría pero no en la práctica. openlatch status muestra qué agentes siguen pendientes, y Niveles de control explica cómo recibe un veredicto cada agente. Una máquina no está terminada hasta que el desarrollador abre el agente una vez.

Confirmar la instalación

openlatch status
openlatch doctor

Una máquina está instalada cuando openlatch doctor no informa de ningún problema y la máquina aparece en el registro de agentes de la consola con sus agentes y un propietario. Verificar y desplegar cubre esa comprobación máquina a máquina y en toda una oleada.

Detrás de un proxy corporativo

Cada llamada saliente del cliente recorre una única ruta de salida. El tráfico del bucle local de la máquina nunca la recorre. La ruta se resuelve ajuste por ajuste, así que una opción puede fijar la URL del proxy mientras el paquete de certificados viene de otra parte.

Orden	Origen	Úsalo para
1	Las opciones del comando openlatch init	Fijar la ruta en el momento de la inscripción
2	OPENLATCH_PROXY y sus variables hermanas	El único canal autorizado a llevar una credencial de proxy
3	La configuración propia del cliente, escrita en la instalación	Lo que lee el cliente cuando arranca con la sesión, donde no existen variables de shell
4	La familia estándar de variables https_proxy	Un entorno que ya las exporta para todas las herramientas
5	El descubrimiento del sistema operativo	Una inscripción sin configuración en un escritorio gestionado
6	Directo	El último recurso. Se puede rechazar, para que una ruta sin resolver falle en lugar de salir en directo

Lo que permitió la instalación se escribe en la configuración propia del cliente, con su origen. El cliente arranca con la sesión del usuario y no hereda ninguna variable del shell de instalación, así que una ruta que solo existía en una variable de entorno dejaría la máquina saliendo en directo al terminar la sesión.

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

El paquete de certificados se combina encima del almacén de confianza del sistema, sin sustituirlo nunca, y la verificación nunca se desactiva. Negotiate usa la identidad de la sesión iniciada, con un nombre de principal de servicio que por defecto es HTTP/ seguido del host del proxy. NTLM se rechaza por diseño, así que un entorno solo NTLM necesita un cambio en el proxy antes de la inscripción.

Se rechaza una credencial pasada dentro de --proxy, porque cualquier proceso del host puede leer los argumentos de la línea de comandos. Proporciónala con OPENLATCH_PROXY o responde a la pregunta en un terminal. En ambos casos, la contraseña pasa al almacén de credenciales del sistema, nunca acaba en un archivo en disco y se enmascara en cada línea de registro.

Precaución

En un host detrás de un proxy, las direcciones del bucle local deben estar en la lista de exclusiones del proxy del shell que lanza tus agentes. Algunos agentes reciben esa entrada automáticamente en la instalación. Cuando un agente no tiene dónde recibirla, exporta NO_PROXY=127.0.0.1,localhost en el shell que lo lanza. Sin ello, el tráfico del agente hacia el cliente sale hacia el proxy corporativo en lugar de quedarse en la máquina, y el proxy responde con un error.

Instalaciones gestionadas para parques

Precaución

Usa una clave de API por oleada de despliegue, leída de tu almacén de secretos y revocada en la consola cuando termine la oleada. Nunca escribas la clave en un script, un paquete ni una línea de comandos. Cada ejemplo siguiente pone OPENLATCH_API_KEY en el entorno de la instalación. Cuando la plataforma de gestión puede pasar un valor a un script, como Jamf con el parámetro 4, usa ese canal; cuando no puede, como Intune, el script obtiene la clave del almacén de secretos como primera acción. Trata el cuerpo de un script de despliegue como legible: una plataforma de gestión lo guarda en texto claro y puede escribirlo en los registros del dispositivo.

Una instalación gestionada ejecuta el mismo script con tres añadidos:

Añadido	Efecto
OPENLATCH_INSTALL_YES	Hace la instalación desatendida
OPENLATCH_NO_INIT	Retiene la inscripción que el script ejecutaría al final, para que tu script ejecute él mismo openlatch init --yes. Con --yes, la inscripción nunca pregunta: falla y nombra lo que necesitaba
OPENLATCH_API_KEY en el entorno	La credencial llega desde tu almacén de secretos en lugar de por un navegador

Ejecuta openlatch doctor como última línea de cada script y recoge su salida, para que una máquina que se instaló pero no está totalmente conectada siga visible en lugar de contarse como terminada.

Script de gestión de equipos, contexto de usuario (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 ejecuta los scripts en silencio y no admite instalaciones interactivas: por eso la instalación es desatendida y --yes es obligatorio. La extensión de gestión obtiene las asignaciones según su propio calendario, así que planifica una oleada en días más que en minutos. Un script en contexto de usuario necesita un usuario con sesión iniciada, y los scripts de plataforma no llegan a los dispositivos que solo están registrados en Microsoft Entra ID; para llegar a los dispositivos personales registrados, usa la ruta de aplicación Win32 con un comportamiento de instalación User, que el diseño sin elevación hace posible.

Ningún ajuste de Intune define una variable de entorno para un script de plataforma. Por eso la llamada al almacén de secretos es la primera acción del script. Pasar la clave como argumento no es una opción: el cliente rechaza una credencial en sus propios argumentos.

Script de gestión de equipos, contexto de usuario (macOS)

Jamf pasa su primer valor personalizado en el parámetro 4, lo que mantiene la clave fuera del cuerpo del script. La política no necesita ningún paso de empaquetado propio, porque la instalación se registra en el directorio personal del usuario. Asocia la política a un desencadenante a nivel de usuario para que la inscripción se ejecute como el desarrollador y no como 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

Gestión de configuración o paso 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

Ejecuta la inscripción en una muestra de la oleada antes de la ejecución completa, y lee la salida de la tarea de informe en esas máquinas. Un tipo de proxy que la instalación no sabe descubrir aparece ahí, y no en todas las máquinas a la vez.

Imagen de contenedor e integración continua

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

La imagen base no lleva nada para el cliente: el script trae el cliente consigo. La credencial se monta en tiempo de ejecución, así que ninguna capa de la imagen la contiene. OPENLATCH_NO_MODIFY_PATH impide que la instalación escriba una línea PATH en un perfil de shell que ningún shell interactivo leerá, y OPENLATCH_INSTALL_DIR coloca el cliente donde el PATH de la imagen ya busca. --no-persistence omite el gestor de servicios, porque un contenedor no tiene sesión de usuario en la que arrancar. La telemetría de producto está desactivada en integración continua sin configuración. Los ejecutores efímeros se inscriben en cada trabajo, y como repetir la instalación es seguro, reintentar un trabajo también lo es.

Qué instala el cliente en una máquina

El cliente se instala y se ejecuta a nivel de usuario. No se necesitan derechos de administrador, no se escribe nada en un directorio del sistema y no se registra ningún servicio a nivel de máquina.

Elemento	Detalle
Una única unidad instalada	El cliente de OpenLatch, instalado una vez por máquina que ejecuta un agente
Dónde se coloca	Los scripts colocan el cliente en ~/.local/bin en macOS y Linux, y en %LOCALAPPDATA%\openlatch\bin en Windows, y añaden ese directorio al PATH. OPENLATCH_INSTALL_DIR lo cambia de sitio. A propósito, no es el directorio de estado de la fila siguiente
Archivos	El cliente guarda su configuración y sus registros locales en un único directorio: ~/.openlatch en macOS y Linux, %APPDATA%\openlatch en Windows. OPENLATCH_DIR lo cambia de sitio. Todo lo sensible que contiene solo lo puede leer su propietario
Configuración de los agentes	El archivo de configuración de cada agente conectado recibe una entrada que apunta al cliente. Se conserva el contenido existente, y lo que había antes se registra para poder restaurarlo
Arranque	El cliente arranca con la sesión del usuario, bajo el gestor de servicios del sistema operativo
Credenciales	La clave de API, y cualquier credencial de proxy, se guardan en el almacén de credenciales del sistema
Postura de red	Solo escucha en la interfaz de bucle local. No se abre ningún puerto entrante

openlatch uninstall desconecta cada agente que encuentra en la máquina, detiene el cliente y restaura lo que cambió en la configuración de cada agente. openlatch uninstall --purge elimina además el directorio de estado y la credencial guardada. Una purga no elimina los archivos instalados: están fuera del directorio de estado, así que una purga los deja, junto con la línea PATH que añadió el script. Operar cubre la eliminación completa.

En resumen

• Cuatro rutas de instalación llevan a un único estado final. Elige según de dónde viene la credencial y a cuántas máquinas debe llegar la ruta, no según el sistema operativo.
• Los scripts de instalación inscriben una máquina en macOS, Windows y Linux sin ningún entorno de ejecución; npx @openlatch/client init llega al mismo estado final donde Node.js está presente. En todos los casos, la instalación detecta los agentes presentes y conecta cada uno, y volver a ejecutarla es seguro.
• Algunos agentes piden al desarrollador que confirme la conexión una vez. Una máquina no está terminada hasta que eso ocurre.
• Una máquina está instalada cuando openlatch doctor no informa de ningún problema y la máquina aparece en el registro de agentes de la consola con sus agentes y un propietario.
• Una clave de API por oleada, leída de tu almacén de secretos en tiempo de ejecución, nunca en un script, un paquete ni una línea de comandos.