Latchkey

Menú de documentación

Primeros pasos Panel y analíticas Runners gestionados

1. Descripción general de los runners
2. Ejecuta tu primer job
3. Migrar desde GitHub-hosted
4. Latchkey CLI
5. La página de Runners
6. Runners personalizados (AI Scan)
7. Autocuración
8. Imagen del runner y software
9. Aprovisionamiento y pools en caliente
10. Límites y concurrencia Caché Equipo y notificaciones
11. Equipo y roles
12. Notificaciones
13. Integración con Slack Facturación y planes
14. Planes y prueba
15. Gestión de la facturación
16. Uso y minutos gratuitos Ayuda
17. Solución de problemas
18. Preguntas frecuentes
19. Arquitectura de seguridad
20. Seguridad y permisos Archivos de workflow
21. Archivos de workflow

Da a Claude Code, Cursor o cualquier agente compatible con MCP acceso seguro a tus fallos de CI, además de re-ejecuciones de workflows opcionales y jobs puntuales en runners nuevos, para que pueda triar, corregir y verificar desde tu editor.

En resumen

1. Ajustes, claves de API y agentes crea claves lk_live_ para el servidor MCP de Latchkey en https://latchkey.dev/mcp.
2. Los agentes conectados (Claude Code, Cursor, cualquier cliente MCP) pueden triar fallos, obtener paquetes de fallo, consultar el estado de las ejecuciones, seguir los logs, impulsar correcciones desde tu editor, ejecutar jobs puntuales en runners nuevos, y listar y cancelar sus jobs.
3. La página AI Insight puede entregar un hallazgo directamente a tu agente con Copiar prompt o un atajo Configurar MCP.
4. Las claves son de solo lectura por defecto, con alcance de workspace, se muestran una sola vez al crearlas y se pueden revocar en cualquier momento. Re-ejecutar workflows, leer el estado y los logs de jobs de CLI, y ejecutar jobs son cada uno un opt-in separado y explícito al crear la clave.

app.latchkey.dev / acme / settings

Pestaña Ajustes, claves de API y agentes. El panel de claves de API, con 3 claves, recorre tres pasos: 1 Detalles, 2 Copiar clave y 3 Conectar agente. En el paso 2 la nueva clave ci-agent-codex se muestra una vez completa, bajo la advertencia Copia tu clave ahora. No podrás verla de nuevo. y la línea de que Latchkey solo almacena una versión con hash. El botón de continuar, Ya la guardé, continuar, espera hasta que la clave se copie. La clave se copia y el paso 3 abre Conecta tu agente con Claude Code elegido: el comando claude mcp add --transport http latchkey https://latchkey.dev/mcp --header "Authorization: Bearer" con la nueva clave ya rellenada, una casilla para leer la clave desde $LATCHKEY_API_KEY en lugar de pegarla, una nota de que el comando escribe el token en texto plano en ~/.claude.json, y el comando de instalación de Latchkey CLI npm install -g @latchkeydev/cli. El comando se copia. Bajo los pasos, la tabla Activas lista ci-agent-codex primero, marcada como Nueva, enmascarada a su prefijo lk_live_7f3a y sus últimos cuatro caracteres 3f2a, con acceso mcp:read, jobs:read y jobs:run, nunca usada y sin caducidad, luego deploy-bot, y cursor-ci marcada como Sin usar 30d.

FIG. 2.6-A La clave completa se muestra una vez, cuando se crea; después de eso la lista solo muestra su prefijo y sus últimos cuatro caracteres, y el acceso con el que se creó la clave nunca cambia. Copia la clave primero: el paso 3 entonces da el comando de conexión con la clave ya incluida.

Latchkey incluye un servidor MCP: tu agente de codificación con IA se conecta a él con una clave de API de Latchkey y puede traer contexto real de fallos de CI (ejecuciones fallidas, logs, paquetes de diagnóstico) directamente a tu sesión de editor. En lugar de copiar y pegar logs en un chat, tu agente pregunta directamente a Latchkey y obtiene todo lo que necesita para corregir el fallo.

Esta es la mitad de traspaso de la autocuración: la autocuración corrige fallos de entorno durante la ejecución y nunca toca tu código fuente, así que cuando el problema real es un bug en tu código, la compilación falla con honestidad, y ese fallo llega aquí como un paquete listo para corregir para tu agente.

Hay dos formas de entrar: crear una clave tú mismo en Ajustes, claves de API y agentes (la configuración de abajo), o dejar que la página AI Insight lo haga por ti. Los hallazgos que tu propio agente de codificación puede corregir mejor ofrecen Copiar prompt, un prompt listo para pegar en tu agente, y un atajo Configurar MCP que crea una clave llamada coding-agent y muestra el comando de conexión exacto. La clave generada caduca en 90 días y puede ejecutar jobs puntuales en runners facturables (la tarjeta lo indica junto al botón), así que trátala como la credencial con capacidad de gasto que es.

Qué puede hacer un agente conectado

El servidor expone trece capacidades: once herramientas que tu agente invoca para obtener datos y realizar acciones, y dos flujos de prompt que orquestan una tarea completa:

Listar ejecuciones fallidash

Enumera las ejecuciones recientes de workflows fallidos con sus metadatos clave. También aparecen los jobs de CLI fallidos.

Obtener paquete de falloh

Obtiene el contexto completo de un fallo: logs, diagnóstico y detalles del workflow.

Consultar estado de ejecuciónh

Consulta el estado de una ejecución servida por Latchkey, su conclusión y los tiempos por job.

Seguir logs de ejecuciónh

Lee la cola del log depurada de secretos de cualquier job completado, incluidas las ejecuciones en verde.

Re-ejecutar un workflowh

Dispara una ejecución workflow_dispatch para verificar una corrección. Requiere una clave con dispatch habilitado.

Ejecutar un job puntualh

Ejecuta un comando de shell en un runner nuevo de Latchkey. Requiere una clave con jobs habilitados y factura minutos de runner.

Consultar estado de jobh

El estado de un job de CLI y, cuando termina, el código de salida del comando.

Leer log de jobh

La salida de un job de CLI desde el principio o sus últimas líneas, para que el agente lea el resultado del comando que ejecutó o vea que un job largo sigue escribiendo.

Listar jobsh

Los jobs del workspace, los más recientes primero, o solo los que siguen en cola o en ejecución, cada uno con su estado, tiempo transcurrido y coste hasta el momento.

Cancelar un jobh

Termina un job que el agente inició, de inmediato si aún está esperando en la cola. Requiere una clave con jobs habilitados.

Establecer un presupuesto de loteh

Establece o reduce un presupuesto para un lote de jobs. Una vez que sus jobs han costado esa cantidad a tarifas de lista, Latchkey no inicia más. Requiere una clave con jobs habilitados.

Corregir un fallo de CIprompt

Impulsa una corrección guiada de un fallo específico desde dentro de tu editor.

Triar fallos de CIprompt

Examina qué está fallando en tus repositorios monitorizados y prioriza.

Nunca las invocas por su nombre. Le haces a tu agente una pregunta en lenguaje natural, y él decide qué capacidad la responde. Algunos emparejamientos ilustrativos:

Le preguntas a tu agente	Capacidad a la que recurre
"¿Qué está fallando en nuestros repos ahora mismo?"	Triar fallos de CI
"Muéstrame las ejecuciones fallidas recientes de este repo"	Listar ejecuciones fallidas
"Trae todo lo que tengas sobre esa ejecución fallida"	Obtener paquete de fallo
"Corrige la compilación que falla"	Corregir un fallo de CI
"¿Pasó esa ejecución? ¿Cuánto tardó cada job?"	Consultar estado de ejecución
"Muéstrame el final del log del job de despliegue"	Seguir logs de ejecución
"He subido la corrección, re-ejecuta CI y vigílalo"	Re-ejecutar un workflow
"Ejecuta la suite de tests en un runner Linux limpio"	Ejecutar un job puntual
"¿Terminó ese job? ¿Qué imprimió?"	Consultar estado de job y Leer log de job
"¿Qué sigue en ejecución?"	Listar jobs
"Dale a este lote de jobs un presupuesto de $5"	Establecer un presupuesto de lote

Cómo es una sesión

Dos sesiones ilustrativas. La redacción exacta, y las respuestas exactas del agente, variarán según el agente; la forma del intercambio es lo importante.

Abres tu editor y preguntas: "¿Qué está fallando en nuestros repos?" El agente ejecuta el flujo Triar fallos de CI y vuelve con un examen de los fallos en tus repositorios monitorizados, priorizado. Lo acotas: "¿Cuáles de esos importan más para el lanzamiento?" y el agente razona sobre los mismos datos sin que tú abras nunca una pestaña de CI.

El valor es que el bucle se queda en un solo lugar: pregunta, contexto, siguiente pregunta, todo dentro de la sesión del editor donde harás la corrección.

Preguntas: "Trae el paquete de fallo de la última compilación en rojo y corrígelo." El agente lista las ejecuciones fallidas recientes para encontrar la correcta, obtiene el paquete completo de ella (logs, diagnóstico y detalles del workflow), y luego impulsa una corrección guiada desde dentro de tu editor, proponiendo cambios para que los revises.

Fíjate en lo que no ocurrió: el agente nunca tocó los ajustes de Latchkey ni GitHub a través de la clave. Leyó contexto de fallos; los cambios de código pasaron por ti.

Qué contiene un paquete de fallo

El paquete de fallo entrega a tu agente lo que de otro modo reconstruiría a mano:

• La causa raíz, en lenguaje natural.
• El código de salida del paso que falla y el archivo fuente exacto donde surgió el error.
• Los logs completos capturados del paso que falla, incluida la salida que GitHub oculta en su visor de logs; los logs muy grandes conservan su porción final y lo indican. Los secretos se eliminan antes de que los logs salgan de Latchkey.
• Qué investigó ya la autocuración y por qué se detuvo, además de la definición del workflow.

Configuración

01

Crea una clave de API

Abre Ajustes, claves de API y agentes (los propietarios y administradores gestionan las claves). Haz clic en Generar clave, nómbrala según dónde vivirá (por ejemplo, "Cursor en mi portátil") y elige una caducidad: Nunca (la opción por defecto), 30 días, 60 días, 90 días o 1 año. Marca las capacidades que necesita la clave (dispatch de workflows, lectura del estado y logs de jobs de CLI, ejecución de jobs de CLI); las capacidades se fijan al crearla.

02

Copia la clave de inmediato

La clave completa (empieza por lk_live_) se muestra una vez, al crearla. Después de eso la interfaz solo muestra un marcador de posición. Trátala como una contraseña; si la pierdes, revócala y crea una nueva.

03

Conecta tu agente

El bloque Conecta tu agente en la misma pestaña de ajustes muestra el comando exacto para tu workspace. Para Claude Code se ve así:

terminal

1claude mcp add --transport http latchkey \

2 https://latchkey.dev/mcp \

04

Úsalo

Pregunta a tu agente sobre CI que falla ("¿qué está fallando en nuestros repos?", "trae el paquete de fallo de la última compilación en rojo y corrígelo"). Cualquier cliente compatible con MCP que admita transporte HTTP con una cabecera bearer funciona igual.

Re-ejecutar workflows tras una corrección (opt-in)

Por defecto una clave es de solo lectura. Si quieres que el bucle se cierre (el agente corrige el código, lo sube, re-ejecuta CI y lo vigila hasta que pasa a verde), crea una clave con Permitir dispatch de workflows marcado. Esa clave además lleva el alcance mcp:dispatch, y tu agente puede entonces disparar ejecuciones workflow_dispatch en tus repositorios monitorizados, consultarlas con la herramienta de estado de ejecución cuando sus jobs se ejecutan en runners de Latchkey, y leer sus logs cuando terminan. Las ejecuciones en verde también son legibles, así que el agente puede confirmar la corrección, no solo observar el fallo.

• El dispatch funciona solo en repositorios que tu workspace monitoriza, y solo para workflows que declaran el disparador workflow_dispatch.
• Las claves existentes nunca obtienen dispatch de forma retroactiva; genera una nueva clave con la casilla habilitada.
• La re-ejecución ejecuta lo que haya en la rama contra la que haces dispatch; sube primero la corrección y luego haz dispatch.

Ejecutar jobs en runners nuevos (opt-in)

El segundo opt-in de escritura es ejecutar jobs puntuales. Una clave creada con Permitir ejecutar jobs de CLI (incluye lectura) lleva el alcance jobs:run (jobs:read, para estado y logs, viene con él), y tu agente puede entonces usar la herramienta Ejecutar un job puntual: un comando de shell en un runner de Latchkey nuevo y aislado, facturado como minutos de runner ordinarios del mismo pool de minutos gratuitos que tus workflows. El runner arranca limpio, sin contenido de repositorio; los jobs que necesitan tu árbol de trabajo pasan por la Latchkey CLI, que lo empaqueta y lo sube. Permitir leer el estado y los logs de jobs de CLI es la concesión más limitada (jobs:read solo) para una clave que debe seguir jobs pero nunca iniciarlos.

• Los jobs tienen por defecto un tiempo de espera de 30 minutos, configurable hasta 3 horas, y el agente elige un tamaño de runner (small cuando no lo hace).
• Una clave con jobs habilitados gasta dinero: cada job se factura a la tarifa estándar por minuto del runner. Nombra la clave para el agente que la posee y asígnale una caducidad.
• Cancela un job con la herramienta Cancel a job o latchkey cancel, que requieren el scope jobs:run, o con Cancel job en su fila bajo Running now en la página Runs.

acme-api · zsh · latchkey run

En una terminal en ~/acme-api, un agente de programación ejecuta latchkey run 'npm test'. La CLI empaqueta y sube el árbol de trabajo y el log del job se transmite de vuelta: state: running, luego vitest. src/billing/invoice.test.ts pasa. En src/auth/refresh.test.ts la prueba keeps a token with an hour left falla con AssertionError: expected true to be false // Object.is equality, y el resumen indica 1 failed y 411 passed de 412 tests. La CLI imprime state: failed y Job cli-3a7f1e92-6c4b-4d18-8e5a-2b9c0d7f4a16 failed (exit 1). El agente escribe el comentario # fix: convert expires_at from seconds to ms in src/auth/refresh.ts y luego ejecuta latchkey run 'npm test' de nuevo. El nuevo job empaqueta el árbol editado de la misma forma, src/auth/refresh.test.ts pasa, los 412 tests en 38 archivos pasan, y la CLI imprime state: succeeded y Job cli-9e04b6d3-1f7a-4c2e-b5d8-6a3f0e1c7b29 succeeded (exit 0).

FIG. 2.6-B Un agente maneja latchkey run como cualquier comando de shell: el test que falla ya está en el stream que lee, y el código de salida, 1 y luego 0, es el veredicto. Cada ejecución empaqueta el árbol de trabajo de nuevo, así que la corrección llega al siguiente job sin un commit ni un push.

Modelo de seguridad

• Solo lectura por defecto. Las claves pueden leer datos de fallos de CI y de ejecuciones; cambiar cualquier cosa en Latchkey o GitHub está desactivado por defecto. Las escrituras a las que una clave puede optar al crearse son el dispatch de workflows (mcp:dispatch), la ejecución de jobs en runners de Latchkey (jobs:run) y la configuración de secretos del workspace (secrets:write). Una clave de secretos puede establecer o reemplazar un secreto pero nunca leerlo de vuelta, y ninguna clave accede a ningún otro ajuste de Latchkey ni a acciones arbitrarias de GitHub.
• Con alcance de workspace. El workspace se deriva de la propia clave, así que una clave solo puede ver los datos de su propio workspace.
• Revocable. Revoca cualquier clave desde Settings, API keys and agents: una clave con capacidad de escritura (dispatch, jobs o secretos) pierde el acceso de inmediato, y una clave de solo lectura en aproximadamente un minuto. Las claves revocadas permanecen listadas bajo una sección "Revoked (n)" para auditoría.

Qué significan esas tres propiedades en la práctica. El solo lectura por defecto acota el radio de impacto de una filtración: una clave por defecto robada expone datos de fallos de CI (incluidos extractos de logs), por lo que aun así deberías protegerla, pero no puede abrir PRs, alterar ajustes ni actuar en GitHub en tu nombre. Una clave robada con dispatch habilitado puede además desencadenar workflows despachables en tus repositorios monitorizados, una clave robada con jobs habilitados puede ejecutar comandos en runners facturables de tu workspace, y una clave robada con secretos habilitados puede establecer o reemplazar cualquier secreto que lean tus jobs (aunque nunca puede leerlo de vuelta), que es exactamente por lo que cada escritura es una opción por clave con una advertencia al crearse, no un valor por defecto. El alcance de workspace significa que no hay nada que configurar ni nada que equivocar: la propia clave determina lo que puede ver, y nunca puede ver otro workspace. Y como la revocación es rápida y las claves revocadas permanecen listadas para auditoría, la respuesta segura ante cualquier duda es simplemente revocar y reemitir.

Dos hábitos de bajo esfuerzo que mantienen esto limpio: crea una clave separada para cada herramienta o máquina (el aviso de nombre al crearla, como "Cursor on my laptop", existe exactamente para esto), de modo que revocar una clave nunca rompa las demás; y elige la caducidad más corta que encaje con tu forma de trabajar, reservando never para configuraciones que sigas activamente. La gestión de claves corresponde a owners y admins; consulta Team and roles y Security and permissions para el modelo más amplio.

Latchkey también publica descriptores legibles por máquina para que un agente pueda descubrir la superficie sin que se le indique. La API REST de Jobs se sirve desde https://api.latchkey.dev y está completamente descrita por una especificación OpenAPI 3.1; el servidor MCP tiene su propio manifiesto que lista cada herramienta y el scope que necesita.

Archivo	Qué es
/openapi.json	Contrato OpenAPI 3.1 para la API de Jobs: operaciones, esquemas tipados, scopes y formas de error.
/.well-known/mcp/manifest.json	Descriptor del servidor MCP: transporte, autenticación y las once herramientas con sus scopes.
/agent.txt	Breve resumen en texto plano sobre cuándo recurrir a Latchkey y cómo llamarlo.
/llms.txt	Índice del sitio y su contenido, con una sección de cuándo usarlo.

Cada página de contenido del sitio también tiene una versión markdown en la misma URL más .md, enlazada desde el encabezado de la página como un enlace rel="alternate". Contiene el mismo contenido sin el marcado de la página, lo que es mucho más económico de leer para un agente.

Q.01¿Qué puede hacer realmente un agente de IA conectado?

Triar fallos, extraer paquetes de fallos, comprobar el estado de las ejecuciones, seguir logs, impulsar correcciones desde tu editor y ejecutar jobs puntuales en runners nuevos. Cualquier cliente MCP funciona, incluidos Claude Code y Cursor, contra el servidor MCP de Latchkey en https://latchkey.dev/mcp.

Q.02¿Las claves de API son de solo lectura?

Por defecto, sí. Las claves tienen alcance de workspace, se muestran una vez al crearse y son revocables en cualquier momento. Volver a ejecutar workflows, leer el estado y los logs de jobs de la CLI, y ejecutar jobs son cada uno una opción explícita separada elegida al crear la clave, así que nada obtiene acceso de escritura por accidente.

Q.03¿Cómo le paso un hallazgo concreto a mi agente?

Desde la página AI Insight. Copy prompt pone el hallazgo y su contexto en tu portapapeles en un formato sobre el que un agente puede actuar, y se ofrece un atajo Set up MCP si aún no existe ninguna clave, para que no tengas que reconstruir el problema a mano.

Referencias

• GitHub Actions documentation