Documentação

Agentes de codificação na sua própria máquina

Execute as funções do seu perfil AI em um agente de codificação na máquina de quem iniciar a tarefa, usando as ferramentas do CoRoid e nada da máquina.

Uma função do seu perfil AI pode ser executada em um agente de codificação na sua própria máquina em vez de um modelo que o CoRoid chama. O agente realiza o raciocínio da função ali, conectado conforme você configurou, na sua própria conta com o provedor. O CoRoid fornece as ferramentas da função e mantém todo o restante do fluxo de trabalho: a tarefa, as verificações e barreiras, o registro do que aconteceu.

O que abrange

  • Todas as funções de um perfil, exceto o mecanismo de decisão: o Arquiteto e o coordenador, o Desenvolvedor, QA, o Revisor, o testador web, o tradutor e os demais. O mecanismo de decisão não é um agente em execução: ele consulta um modelo de decisões para obter a probabilidade de cada resposta permitida, algo que um agente de codificação não fornece.
  • Quatro agentes: Codex e OpenCode, e apenas para algumas organizações, por enquanto, Claude Code e Cursor. Cada um opera sob o seu próprio plano com o provedor (veja O plano do seu agente).
  • Todas as maneiras como uma tarefa é executada. No modo coordenador, o coordenador e os filhos para os quais encaminha o trabalho são executados no agente, como qualquer outra função.

O plano do seu agente

O agente trabalha com seu próprio login e sob o seu plano com o provedor: Anthropic para Claude Code, OpenAI para Codex, Cursor para Cursor e quaisquer provedores que você configurar no OpenCode. O CoRoid nunca vê esse login, e não revende ou compartilha o plano de ninguém: cada pessoa conecta sua própria máquina, e o agente realiza o trabalho que eles iniciaram.

Se os termos de um plano permitem seu uso por meio de outro produto e para quais tarefas, isso depende de um acordo entre você e o provedor. Isso varia entre provedores, entre seus planos pessoais e empresariais, pode depender da quantidade de trabalho processada e pode mudar. Leia os termos do seu plano e consulte o provedor quando não estiver claro.

Uma organização que atribui funções aos agentes deve verificar o mesmo nos planos de seus membros. Sua política pode permitir apenas os agentes cujos termos foram analisados (veja O que sua organização permite).

Como se conecta

Sua máquina

Conector CoRoid

Código aberto. Inicia o agente para uma rodada em um diretório vazio e novo, e o encerra após.

Seu agente de codificação

O agente que você usa, logado como você, com suas próprias ferramentas desativadas.

  1. 1Solicita trabalho. Cada solicitação tem até 25 segundos; o conector relata o que o agente diz a cada 3 segundos.
  2. 2Invoca as ferramentas da função. Com um token válido apenas para essa rodada, que deixa de funcionar ao final dela.
  3. 3Consulta seu modelo. Como ocorreria sem o CoRoid. O CoRoid nunca vê esse login.

CoRoid

Orquestrador

Distribui o trabalho da função para a máquina da pessoa que iniciou a tarefa (1).

As ferramentas da função

Executa na área de isolamento da tarefa, onde seu código permanece (2).

O provedor do agente

Responde às solicitações do modelo do agente sob seu próprio login, no seu plano (3).

Nada acessa a máquina: o conector não abre porta alguma, não envia nenhum de seus arquivos e não executa comando próprio.

Na máquina permanecem seu login no agente e o que o agente guarda de uma rodada.

Toda conexão começa na máquina e sai via HTTPS. O repositório permanece na área de isolamento da tarefa no CoRoid; o agente trabalha nele apenas por meio das ferramentas da função atribuída.

A máquina trabalha para o CoRoid por meio do conector CoRoid, um pequeno programa de código aberto que você instala e executa. Toda conexão começa na máquina: o conector solicita trabalho ao CoRoid, o agente utiliza as ferramentas da função na área isolada da tarefa e o agente pede respostas ao modelo ao seu provedor, com seu login. O conector não abre portas nem envia arquivos da máquina. A segurança do conector explica o que ele faz e o que não faz, e como verificar uma versão.

Conectar uma máquina

  1. Instale o agente na máquina e faça login nele, como faria para usá-lo você mesmo.

  2. Instale o conector, com Homebrew no macOS ou Linux:

    brew install coroid-ai/tap/coroid-connector

    ou com npm, em qualquer lugar com Node.js 20 ou superior:

    npm install --global @coroid/connector
  3. Para Codex ou Claude Code, adicione o agente: coroid-connector add codex (ou add claude). Isso instala o adaptador ACP do agente, que traz sua própria cópia do agente (cerca de 350 MB), em ~/.coroid/connector, a partir dos pacotes que o conector libera com hash fixo. OpenCode e Cursor não precisam ser adicionados: o CoRoid usa sua própria instalação.

  4. Abra Configurações → Conexões → Suas máquinas e execute o comando mostrado ali (coroid-connector --api …). Seu navegador abrirá: aprove a máquina para sua organização. Aprove apenas um conector que você iniciou há pouco.

O conector então continuará em execução até você interrompê-lo, solicitando trabalho ao CoRoid. Suas máquinas lista a máquina como conectada, com os agentes que o conector encontrou nela e a versão de cada um. Um agente só aparece como pronto em uma versão que o CoRoid testou; em outra versão, ele é exibido mas não é usado.

coroid-connector status mostra o mesmo da máquina, com o modelo definido para cada agente.

Só você vê suas máquinas. Desconectar encerra o login da máquina e seu conector para dentro de um minuto.

Atribuir uma função a um agente

Um proprietário de organização faz isso em um perfil personalizado, em Configurações → Perfil AI (veja Perfis AI).

  1. Abra os detalhes do perfil. No primeiro campo de uma função, a lista começa com Na sua própria máquina: os agentes oferecidos à sua organização e, ao lado de cada um, se uma máquina sua já os tem prontos.
  2. Escolha o agente. Duas novas opções aparecem:
    • Modelo em : o modelo que o agente deve usar para essa função, dentre os modelos que suas máquinas conectadas relatam para ele. Conforme definido na máquina deixa o agente no modelo que seu proprietário configurou nele.
    • Sem uma máquina conectada: o modelo que executa a função quando nenhuma máquina assume o trabalho. É o modelo que a função possuía.
  3. Salvar.

Escolher um modelo no primeiro campo novamente afasta o agente e leva consigo o modelo nomeado para ele.

O que acontece quando uma tarefa é executada

A atribuição pertence à organização; a máquina pertence à pessoa. Quando uma função é iniciada, o CoRoid procura por uma máquina da pessoa que iniciou a tarefa:

  • conectada a esta organização no último minuto,
  • com o agente atribuído pronto em uma versão que o CoRoid já testou,
  • e oferecendo o modelo nomeado, se a atribuição especificar um.

Se houver uma, o trabalho da função vai para essa máquina. Caso contrário, a função roda no modelo sob Sem uma máquina conectada, exatamente como teria ocorrido. Nada espera por uma máquina. Trabalhos que ninguém iniciou (uma automação baseada em evento ou agendamento) não têm essa máquina e rodam em seu modelo.

Na máquina, o conector inicia o agente em um diretório novo e vazio e fornece à sua sessão um conjunto de ferramentas: as ferramentas do CoRoid para esta função, acessíveis apenas para este trabalho. O desenvolvedor altera o código por meio delas, no espaço de trabalho da tarefa no CoRoid, como um modelo faz; o QA e o revisor avaliam essa alteração por meio delas. Uma mensagem adicionada à tarefa enquanto o agente trabalha chega a ele com o próximo resultado da ferramenta.

Uma função que espera retorna ao agente. O coordenador entrega o trabalho ao desenvolvedor, ao QA e ao revisor e espera por cada um; um subprocesso pode esperar pela resposta do coordenador. Quando a espera termina, a função retorna ao agente, que recebe a conversa até então. Uma máquina pode executar até quatro funções simultaneamente (conector 0.4.0), de modo que os exploradores iniciados pelo desenvolvedor rodam ao lado dela.

Se a máquina parar de responder no meio de uma função, a função continua na mesma conversa em seu modelo na nuvem, que é informado sobre o ocorrido. Uma tarefa interrompida também para o agente. Quando uma função termina, seu agente é parado e o diretório é removido.

O que permanece na sua máquina

O conector remove o diretório onde a função foi executada. O que o agente mantém do trabalho em seu próprio armazenamento depende do agente:

AgenteO que ele mantém
Claude CodeNenhuma transcrição: o conector o inicia com persistência de sessão desativada
CodexUma transcrição de cada sessão em ~/.codex/sessions, incluindo os arquivos que leu
OpenCodeSuas sessões em seu próprio banco de dados em ~/.local/share/opencode
CursorCada sessão em seu próprio banco de dados em ~/.cursor/acp-sessions

Codex, OpenCode e Cursor não oferecem opção para isso atualmente. Se sua organização precisar manter o código fora dos laptops, permita apenas o Claude Code em sua política (veja abaixo).

O que sua organização permite

Um proprietário ou administrador decide em Configurações → Identidade e acesso → Política da organização, sob Agentes de programação nas máquinas das pessoas, em todos os planos:

  • Permitir agentes de programação nas máquinas das pessoas. Quando está desativado, todas as funções rodam em seu modelo, incluindo uma função que um perfil já atribuiu a um agente.
  • Uma opção por agente sua organização tem disponível, além do que esse agente mantém na máquina. Com todos os agentes ativados, um agente que o CoRoid oferecer posteriormente também fica ativado.

O formulário de perfil do AI mostra apenas os agentes permitidos pela política, e uma função não pode ser reatribuída a outro. Uma função atribuída antes da mudança de política mantém sua atribuição, e o formulário indica que ela roda em seu modelo. A política de um projeto pode restringir a da organização, mas nunca ampliá-la.

O que o agente pode e não pode fazer

  • Apenas as ferramentas do CoRoid. As ferramentas próprias de cada agente (seu shell, edição de arquivos, busca na web, seus próprios servidores MCP e conectores) são desativadas para a sessão, conforme o agente fornece. Uma solicitação para usar qualquer outra coisa é recusada.
  • Nada da máquina. O agente não trabalha no seu checkout e não obtém arquivos da máquina. O CoRoid também não tem acesso à máquina: o conector apenas pede trabalho ao CoRoid e relata o que o agente diz.
  • As mesmas verificações. O que o agente altera passa pelas mesmas etapas de QA, revisão, portas e limites de etapas que o trabalho de um modelo.
  • O que é enviado. O que a função precisa (o código que lê, os requisitos, os resultados de suas ferramentas, as imagens de um anexo) vai para a máquina e, de lá, para o provedor do agente com o login que o agente tem lá. Se sua organização precisar manter o código com provedores específicos, leve isso em conta antes de atribuir uma função a um agente.

Custo e registros

O raciocínio do agente é atribuído à pessoa cuja máquina executou o trabalho, e não ao gasto com modelo do CoRoid. A atividade de uma tarefa exibe essa execução da seguinte forma, por exemplo: Codex (gpt-6-luna) no laptop da Ada · não é medido, nunca como tokens zerados. Se uma função utilizar seu modelo em nuvem, essa parte será medida normalmente.

CoRoid registra cada trabalho que encaminha para uma máquina: qual máquina e agente, o nome do modelo, como terminou e quantas chamadas de ferramenta foram feitas.

Exportar e importar

O agente de uma atribuição e seu modelo acompanham o perfil na exportação de configurações, e a escolha de agentes definida pela política acompanha a política organizacional. Uma organização sem agentes locais, que não tenha esse agente disponível ou cuja política não o permita, importará a atribuição apenas com seu modelo em nuvem, e a importação indicará isso. Veja Exportar e importar configurações.