Latchkey

Documentation menu

Primeiros passos Dashboard e análises Runners gerenciados

1. Visão geral dos runners
2. Execute seu primeiro job
3. Migre do GitHub-hosted
4. CLI do Latchkey
5. A página de runners
6. Runners personalizados (AI Scan)
7. Autocorreção
8. Imagem e software do runner
9. Provisionamento e pools dinâmicos
10. Limites e concorrência Cache Equipe e notificações
11. Equipe e funções
12. Notificações
13. Integração com Slack Planos e cobrança
14. Planos e teste grátis
15. Gerenciando a cobrança
16. Uso e minutos grátis Ajuda
17. Solução de problemas
18. FAQ
19. Arquitetura de segurança
20. Segurança e permissões Arquivos de workflow
21. Arquivos de workflow

Dê ao Claude Code, Cursor ou qualquer agente compatível com MCP acesso seguro às suas falhas de CI, além de reexecuções de workflow opcionais e jobs avulsos em runners novos, para que ele possa fazer triagem, corrigir e verificar diretamente do seu editor.

Em resumo

1. Configurações, chaves de API e agentes cria chaves lk_live_ para o servidor MCP do Latchkey em https://latchkey.dev/mcp.
2. Agentes conectados (Claude Code, Cursor, qualquer cliente MCP) podem fazer triagem de falhas, baixar pacotes de falha, verificar o status de execuções, acompanhar logs, conduzir correções pelo seu editor, executar jobs avulsos em runners novos e listar e cancelar seus jobs.
3. A página AI Insight pode enviar um achado diretamente ao seu agente com Copiar prompt ou um atalho Configurar MCP.
4. As chaves são somente leitura por padrão, limitadas ao workspace, exibidas uma única vez na criação e revogáveis a qualquer momento. Reexecutar workflows, ler o status e os logs de jobs da CLI e executar jobs são cada um uma adesão explícita e separada na criação da chave.

app.latchkey.dev / acme / settings

Aba Configurações, chaves de API e agentes. O painel de chaves de API, com 3 chaves, percorre três etapas: 1 Detalhes, 2 Copiar chave e 3 Conectar agente. Na etapa 2, a nova chave ci-agent-codex é exibida uma única vez por completo, sob o aviso Copie sua chave agora. Você não poderá vê-la novamente. e a linha de que o Latchkey armazena apenas uma versão com hash. O botão de continuar, Salvei, continuar, espera até que a chave seja copiada. A chave é copiada, e a etapa 3 abre Conecte seu agente com Claude Code selecionado: o comando claude mcp add --transport http latchkey https://latchkey.dev/mcp --header "Authorization: Bearer" com a nova chave já preenchida, uma caixa para ler a chave de $LATCHKEY_API_KEY em vez de colá-la, uma nota de que o comando grava o token em texto puro em ~/.claude.json, e o comando de instalação da CLI do Latchkey npm install -g @latchkeydev/cli. O comando é copiado. Abaixo das etapas, a tabela Ativas lista ci-agent-codex primeiro, marcada como Nova, mascarada com o prefixo lk_live_7f3a e os últimos quatro caracteres 3f2a, com acesso mcp:read, jobs:read e jobs:run, nunca usada e sem expiração, depois deploy-bot e cursor-ci marcada como Não usada há 30d.

FIG. 2.6-A A chave completa é exibida uma única vez, na criação; depois disso a lista mostra apenas o prefixo e os últimos quatro caracteres, e o acesso com o qual a chave foi criada nunca muda. Copie a chave primeiro: a etapa 3 então mostra o comando de conexão com a chave já incluída.

O Latchkey inclui um servidor MCP: seu agente de IA de codificação se conecta a ele com uma chave de API do Latchkey e pode puxar o contexto real de falhas de CI (execuções com falha, logs, pacotes de diagnóstico) direto para a sua sessão no editor. Em vez de copiar e colar logs em um chat, seu agente pergunta diretamente ao Latchkey e recebe tudo o que precisa para corrigir a falha.

Esta é a metade da entrega do autocorreção: a autocorreção corrige falhas de ambiente durante a execução e nunca toca no seu código-fonte; então, quando o problema real é um bug no seu código, o build falha de forma verdadeira, e essa falha chega aqui como um pacote pronto para correção para o seu agente.

Há duas formas de entrar: criar uma chave você mesmo em Configurações, chaves de API e agentes (a configuração abaixo) ou deixar a página AI Insight fazer isso por você. Achados mais bem corrigidos pelo seu próprio agente de codificação oferecem Copiar prompt, um prompt pronto para colar no seu agente, e um atalho Configurar MCP que cria uma chave chamada coding-agent e mostra o comando exato de conexão. A chave criada expira em 90 dias e pode executar jobs avulsos em runners cobráveis (o cartão diz isso ao lado do botão), então trate-a como a credencial com capacidade de gasto que ela é.

O que um agente conectado pode fazer

O servidor expõe treze capacidades: onze ferramentas que seu agente chama para dados e ações, e dois fluxos de prompt que orquestram uma tarefa inteira:

Listar execuções com falhaferramenta

Enumera execuções recentes de workflow com falha e seus metadados principais. Jobs da CLI com falha também aparecem.

Obter pacote de falhaferramenta

Puxa o contexto completo de uma falha: logs, diagnóstico e detalhes do workflow.

Verificar status da execuçãoferramenta

Consulta uma execução atendida pelo Latchkey para status, conclusão e tempo por job.

Acompanhar logs da execuçãoferramenta

Lê o final do log com segredos removidos de qualquer job concluído, inclusive execuções verdes.

Reexecutar um workflowferramenta

Dispara uma execução workflow_dispatch para verificar uma correção. Exige uma chave com permissão de dispatch.

Executar um job avulsoferramenta

Executa um comando de shell em um runner novo do Latchkey. Exige uma chave com permissão de jobs e cobra minutos de runner.

Verificar status do jobferramenta

O estado de um job da CLI e, quando ele termina, o código de saída do comando.

Ler logs do jobferramenta

A saída de um job da CLI desde o início ou suas linhas mais recentes, para que o agente leia o resultado do comando que executou ou veja que um job longo ainda está escrevendo.

Listar jobsferramenta

Os jobs do workspace, dos mais novos aos mais antigos, ou apenas os que ainda estão na fila ou em execução, cada um com estado, tempo decorrido e custo até o momento.

Cancelar um jobferramenta

Encerra um job iniciado pelo agente, imediatamente se ainda estiver na fila. Exige uma chave com permissão de jobs.

Definir orçamento de loteferramenta

Define ou reduz um orçamento para um lote de jobs. Quando os jobs já custaram esse valor pelas tarifas da lista, o Latchkey não inicia mais nenhum deles. Exige uma chave com permissão de jobs.

Corrigir uma falha de CIprompt

Conduz uma correção guiada de uma falha específica de dentro do seu editor.

Fazer triagem de falhas de CIprompt

Levanta o que está falhando nos seus repositórios monitorados e prioriza.

Você nunca chama isso pelo nome. Você faz uma pergunta em linguagem natural ao seu agente, e ele decide qual capacidade responde. Alguns exemplos de combinações:

Você pergunta ao seu agente	Capacidade que ele usa
"O que está falhando nos nossos repositórios agora?"	Fazer triagem de falhas de CI
"Mostre as execuções recentes com falha deste repositório"	Listar execuções com falha
"Puxe tudo o que você tem sobre essa execução com falha"	Obter pacote de falha
"Corrija o build que está falhando"	Corrigir uma falha de CI
"Essa execução passou? Quanto tempo cada job levou?"	Verificar status da execução
"Mostre o final do log do job de deploy"	Acompanhar logs da execução
"Enviei a correção, reexecute o CI e acompanhe"	Reexecutar um workflow
"Execute a suíte de testes em um runner Linux limpo"	Executar um job avulso
"Esse job terminou? O que ele imprimiu?"	Verificar status do job e Ler logs do job
"O que ainda está em execução?"	Listar jobs
"Dê a este lote de jobs um orçamento de R$ 25"	Definir orçamento de lote

Como é uma sessão

Duas sessões ilustrativas. O texto exato e as respostas exatas do agente variam conforme o agente; o formato da troca é o ponto.

Você abre o editor e pergunta: "O que está falhando nos nossos repositórios?" O agente executa o fluxo Fazer triagem de falhas de CI e volta com um levantamento das falhas nos seus repositórios monitorados, priorizadas. Você restringe: "Quais dessas importam mais para o release?" e o agente raciocina sobre os mesmos dados sem que você abra uma aba de CI.

O valor é o ciclo permanecer em um só lugar: pergunta, contexto, próxima pergunta, tudo dentro da sessão do editor onde você fará a correção.

Você pergunta: "Puxe o pacote de falha do build vermelho mais recente e corrija." O agente lista execuções recentes com falha para encontrar a certa, puxa o pacote completo dela (logs, diagnóstico e detalhes do workflow) e então conduz uma correção guiada de dentro do editor, propondo mudanças para você revisar.

Note o que não aconteceu: o agente nunca tocou nas configurações do Latchkey nem no GitHub pela chave. Ele leu o contexto da falha; as mudanças de código passaram por você.

O que há em um pacote de falha

O pacote de falha entrega ao seu agente o que ele reconstruiria manualmente:

• A causa raiz, em linguagem simples.
• O código de saída da etapa com falha e o arquivo-fonte exato onde o erro apareceu.
• Os logs completos capturados da etapa com falha, incluindo a saída que o GitHub esconde no visualizador de logs; logs muito grandes mantêm a parte final e avisam isso. Segredos são removidos antes de os logs saírem do Latchkey.
• O que a autocorreção já investigou e por que ela recuou, além da definição do workflow.

Configuração

01

Crie uma chave de API

Abra Configurações, chaves de API e agentes (proprietários e administradores gerenciam chaves). Clique em Gerar chave, dê um nome conforme o local onde ela será usada (por exemplo "Cursor no meu laptop") e escolha uma expiração: Nunca (o padrão), 30 dias, 60 dias, 90 dias ou 1 ano. Marque as capacidades que a chave precisa (dispatch de workflow, leitura de status e logs de jobs da CLI, execução de jobs da CLI); as capacidades são fixas na criação.

02

Copie a chave imediatamente

A chave completa (ela começa com lk_live_) é exibida uma única vez, na criação. Depois disso a interface mostra apenas um espaço reservado. Trate-a como uma senha; se você a perder, revogue-a e crie uma nova.

03

Conecte seu agente

O bloco Conecte seu agente na mesma aba de configurações mostra o comando exato para o seu workspace. Para o Claude Code, fica assim:

terminal

1claude mcp add --transport http latchkey \

2 https://latchkey.dev/mcp \

04

Use

Pergunte ao seu agente sobre CI com falha ("o que está falhando nos nossos repositórios?", "puxe o pacote de falha do build vermelho mais recente e corrija"). Qualquer cliente compatível com MCP que suporte transporte HTTP com cabeçalho bearer funciona da mesma forma.

Reexecutar workflows após uma correção (adesão opcional)

Por padrão, uma chave é somente leitura. Se você quiser fechar o ciclo (o agente corrige o código, envia, reexecuta o CI e acompanha até ficar verde), crie uma chave com Permitir dispatch de workflow marcado. Essa chave carrega adicionalmente o escopo mcp:dispatch, e seu agente pode então disparar execuções workflow_dispatch nos seus repositórios monitorados, consultá-las com a ferramenta de status de execução quando os jobs rodarem em runners do Latchkey e ler os logs quando terminarem. Execuções verdes também são legíveis, para que o agente confirme a correção, não apenas observe a falha.

• O dispatch funciona apenas em repositórios que seu workspace monitora e apenas para workflows que declaram o gatilho workflow_dispatch.
• Chaves existentes nunca ganham dispatch retroativamente; crie uma nova chave com a caixa de seleção habilitada.
• A reexecução roda o que estiver no branch contra o qual você dispara; envie a correção primeiro e depois dispare.

Executar jobs em runners novos (adesão opcional)

A segunda escrita opcional é executar jobs avulsos. Uma chave criada com Permitir execução de jobs da CLI (inclui leitura) carrega o escopo jobs:run (jobs:read, para status e logs, vem junto), e seu agente pode então usar a ferramenta Executar um job avulso: um comando de shell em um runner novo e isolado do Latchkey, cobrado como minutos normais de runner do mesmo pool de minutos grátis dos seus workflows. O runner inicia limpo, sem conteúdo do repositório; jobs que precisam da sua árvore de trabalho passam pela CLI do Latchkey, que empacota e envia. Permitir leitura de status e logs de jobs da CLI é a concessão mais restrita (jobs:read apenas) para uma chave que deve acompanhar jobs, mas nunca iniciá-los.

• Os jobs têm um tempo limite padrão de 30 minutos, configurável até 3 horas, e o agente escolhe o tamanho do runner (small quando não o faz).
• Uma chave habilitada para jobs gasta dinheiro: cada job é cobrado pela tarifa padrão por minuto do runner. Nomeie a chave para o agente que a possui e defina uma expiração.
• Cancele um job com a ferramenta Cancel a job ou latchkey cancel, que exigem o escopo jobs:run, ou com Cancel job na linha dele em Running now na página Runs.

acme-api · zsh · latchkey run

Em um terminal em ~/acme-api, um agente de codificação executa latchkey run 'npm test'. O CLI empacota e envia a árvore de trabalho e o log do job é transmitido de volta: estado: running, depois vitest. src/billing/invoice.test.ts passa. Em src/auth/refresh.test.ts, o teste que mantém um token com uma hora restante falha com AssertionError: expected true to be false // Object.is equality, e o resumo mostra 1 falhou e 411 passaram de 412 testes. O CLI imprime estado: failed e Job cli-3a7f1e92-6c4b-4d18-8e5a-2b9c0d7f4a16 falhou (exit 1). O agente digita o comentário # fix: convert expires_at from seconds to ms in src/auth/refresh.ts e executa latchkey run 'npm test' novamente. O novo job empacota a árvore editada da mesma forma, src/auth/refresh.test.ts passa, todos os 412 testes em 38 arquivos passam, e o CLI imprime estado: succeeded e Job cli-9e04b6d3-1f7a-4c2e-b5d8-6a3f0e1c7b29 teve sucesso (exit 0).

FIG. 2.6-B Um agente executa latchkey run como qualquer comando de shell: o teste que falha já está no fluxo que ele lê, e o código de saída, 1 e depois 0, é o veredito. Cada execução empacota a árvore de trabalho novamente, então a correção chega ao próximo job sem um commit ou push.

Modelo de segurança

• Somente leitura por padrão. As chaves podem ler dados de falha de CI e de execução; alterar qualquer coisa no Latchkey ou no GitHub está desativado por padrão. As gravações que uma chave pode optar por ativar na criação são dispatch de workflow (mcp:dispatch), execução de jobs em runners do Latchkey (jobs:run) e definição de segredos do workspace (secrets:write). Uma chave de segredos pode definir ou substituir um segredo, mas nunca lê-lo de volta, e nenhuma chave alcança qualquer outra configuração do Latchkey ou ações arbitrárias do GitHub.
• Escopo do workspace. O workspace é derivado da própria chave, então uma chave só pode ver os dados do seu próprio workspace.
• Revogável. Revogue qualquer chave em Settings, API keys e agents: uma chave com capacidade de gravação (dispatch, jobs ou segredos) perde o acesso imediatamente, uma chave somente leitura em cerca de um minuto. Chaves revogadas permanecem listadas em uma seção "Revoked (n)" para auditoria.

O que essas três propriedades significam na prática. Somente leitura por padrão limita o raio de impacto de um vazamento: uma chave padrão roubada expõe dados de falha de CI (incluindo trechos de log), por isso você ainda deve protegê-la, mas ela não pode abrir PRs, alterar configurações ou agir no GitHub em seu nome. Uma chave roubada com dispatch habilitado pode adicionalmente acionar workflows despacháveis em seus repositórios monitorados, uma chave roubada com jobs habilitado pode executar comandos em runners pagos no seu workspace, e uma chave roubada com segredos habilitado pode definir ou substituir qualquer segredo que seus jobs leem (embora nunca possa lê-lo de volta), que é exatamente o motivo pelo qual cada gravação é uma opção por chave com um aviso na criação, não um padrão. O escopo do workspace significa que não há nada para configurar e nada para errar: a própria chave determina o que ela pode ver, e ela nunca pode ver outro workspace. E como a revogação é rápida e as chaves revogadas permanecem listadas para auditoria, a resposta segura a qualquer dúvida é simplesmente revogar e reemitir.

Dois hábitos de baixo esforço que mantêm isso limpo: crie uma chave separada para cada ferramenta ou máquina (o prompt de nomeação na criação, como "Cursor on my laptop", existe exatamente para isso), para que revogar uma chave nunca quebre as outras; e escolha a expiração mais curta que se ajuste ao seu modo de trabalho, reservando never para configurações que você acompanha ativamente. O gerenciamento de chaves fica com proprietários e administradores; veja Team and roles e Security and permissions para o modelo mais amplo.

O Latchkey também publica descritores legíveis por máquina para que um agente possa descobrir a superfície sem ser informado. A API REST de Jobs é servida de https://api.latchkey.dev e é totalmente descrita por uma especificação OpenAPI 3.1; o servidor MCP tem seu próprio manifesto listando cada ferramenta e o escopo que ela precisa.

Arquivo	O que é
/openapi.json	Contrato OpenAPI 3.1 para a API de Jobs: operações, esquemas tipados, escopos e formatos de erro.
/.well-known/mcp/manifest.json	Descritor do servidor MCP: transporte, autenticação e todas as onze ferramentas com seus escopos.
/agent.txt	Breve resumo em texto simples sobre quando usar o Latchkey e como chamá-lo.
/llms.txt	Índice do site e seu conteúdo, com uma seção de quando usar.

Toda página de conteúdo do site também tem um gêmeo em markdown na mesma URL mais .md, vinculado no cabeçalho da página como um link rel="alternate". Ele carrega o mesmo conteúdo sem a marcação da página, o que é muito mais barato para um agente ler.

Q.01O que um agente de IA conectado pode realmente fazer?

Triar falhas, baixar pacotes de falha, verificar o status de execuções, acompanhar logs, conduzir correções do seu editor e executar jobs únicos em runners novos. Qualquer cliente MCP funciona, incluindo Claude Code e Cursor, contra o servidor MCP do Latchkey em https://latchkey.dev/mcp.

Q.02As chaves de API são somente leitura?

Por padrão, sim. As chaves têm escopo do workspace, são mostradas uma vez na criação e podem ser revogadas a qualquer momento. Reexecutar workflows, ler o status e logs de jobs do CLI e executar jobs são cada um uma opção explícita separada escolhida na criação da chave, então nada ganha acesso de gravação por acidente.

Q.03Como entrego uma descoberta específica ao meu agente?

Na página AI Insight. Copy prompt coloca a descoberta e seu contexto na sua área de transferência em uma forma que um agente pode agir, e um atalho Set up MCP é oferecido se nenhuma chave existir ainda, para que você não precise reconstruir o problema manualmente.

Referências

• Documentação do GitHub Actions