O Notiamo pode iniciar um agente de IA nos comentários e nas tarefas em aberto de um projeto. O agente faz as alterações e uma pessoa da sua equipe as aprova. Uma execução pode acontecer nos servidores do Notiamo ou em um computador seu. Esta página trata da segunda forma: o runner, um pequeno programa que você instala na sua máquina. Ele é para a equipe da agência.

O que é o runner

O runner espera as execuções do agente que a sua organização coloca na fila no Notiamo. Em cada execução, ele clona o repositório (ou conecta ao site WordPress), inicia o Claude Code com as instruções da execução, envia ao Notiamo o que o agente faz e avisa quando termina.

  • Ele não guarda nenhuma credencial do Claude. Ele inicia o programa claude que já está na máquina. As sessões do runner usam a própria pasta de configuração, separada da sua. O login em si é do Claude Code, guardado pelo Claude Code.
  • Não é um login do Claude dentro do Notiamo. O Notiamo nunca vê nem usa a sua conta do Claude. O runner só executa o seu próprio Claude Code, na sua máquina, para o seu próprio trabalho.

Instale

Você precisa de:

  • Node.js 22 ou posterior;
  • Claude Code 2.1.314 ou mais novo;
  • git 2.31 ou mais novo;
  • no Linux e no WSL2: bubblewrap e socat (Debian ou Ubuntu: sudo apt install bubblewrap socat). No macOS não há mais nada para instalar.

Depois:

  1. No Notiamo, abra Configurações › Execuções do agente. No cartão Runners, clique em Novo runner e dê um nome a ele. Copie o token. Ele aparece uma única vez.
  2. Na máquina, execute:
npx @notiamo/runner init
  1. Cole o token. O init verifica se o Claude Code funciona, executa o login do Claude Code para o runner, instala o serviço e o inicia.
  2. No projeto, defina Onde o agente é executado como Máquina própria.

Quando o init termina, o runner está em execução. Ele volta a iniciar sozinho depois de um login ou de uma reinicialização.

Comandos

Comando O que faz
npx @notiamo/runner init Configura o runner: token, login do Claude Code, instala e inicia o serviço.
npx @notiamo/runner@latest update Leva o runner para a versão mais recente. O token, o nome e o login continuam.
npx @notiamo/runner status Diz se o serviço está instalado e em execução e mostra a última linha do log.
npx @notiamo/runner logs Mostra as últimas 50 linhas do log.
npx @notiamo/runner stop Para o serviço até o próximo login ou a próxima inicialização.
npx @notiamo/runner uninstall Remove o serviço. A pasta do runner continua.
npx @notiamo/runner env <projectId> Cria ou mostra o arquivo env que esta máquina dá às execuções de um projeto.
npx @notiamo/runner start Executa em primeiro plano. O serviço executa isto; você raramente precisa dele.

O serviço é um agente launchd com.notiamo.runner no macOS, uma Tarefa Agendada “Notiamo runner” no Windows e uma unidade de usuário systemd notiamo-runner no Linux.

Dois runners em uma máquina

npx @notiamo/runner init --profile staging configura um segundo runner, separado. Ele tem a própria pasta (~/.notiamo-runner/profiles/staging) e o próprio serviço. Adicione --profile staging a todos os comandos desse runner. O nome de um perfil tem letras, dígitos e hifens, de 1 a 32 caracteres.

O que o agente pode e não pode tocar

Cada execução recebe o próprio arquivo de configurações do Claude Code. Três coisas mantêm o agente no seu lugar.

As ferramentas de arquivo ficam na pasta da execução. As ferramentas de arquivo do próprio Claude (ler, editar, escrever, buscar) recusam tudo o que está fora da pasta da execução. Qualquer chamada que pediria permissão é recusada, porque não há ninguém para responder.

Os comandos de shell são executados na sandbox do sistema operacional. No macOS (Seatbelt) e no Linux ou WSL2 (bubblewrap e socat), todo comando que o agente executa em um shell fica confinado. Se a sandbox não consegue iniciar, a execução não inicia.

Nenhuma credencial da máquina chega ao agente. O Claude Code recebe apenas uma lista curta de variáveis de ambiente (PATH, HOME, USER, LOGNAME, SHELL, LANG, LC_ALL, LC_CTYPE, TERM, TMPDIR, TZ, XDG_*, as configurações de proxy e de certificado) mais as da própria execução. Ele nunca recebe SSH_AUTH_SOCK, GH_TOKEN, GITHUB_TOKEN, NPM_TOKEN, AWS_* nem ANTHROPIC_*. O git do agente não enxerga nenhuma configuração global ou de sistema do git.

O que a sandbox do shell permite e nega:

  • Leitura negada: as pastas dos outros projetos (inclusive as de outras execuções ao mesmo tempo), os arquivos do próprio runner e os seus arquivos e pastas de credenciais (chaves SSH, logins de nuvem, logins de registros de pacotes, credenciais do git).
  • Escrita permitida: só na pasta da execução e na pasta de cache de pacotes do projeto, ao lado dela. O .git/hooks e o .git/config da execução são somente leitura.
  • Rede permitida: GitHub, npm, Notiamo, o site WordPress (em uma execução WordPress) e os hosts que você adiciona em Hosts adicionais que o agente pode aceder no cartão Runners. Todo o resto é recusado.

O agente nunca faz push e não guarda credenciais. O runner faz o push da branch da execução depois do trabalho do agente.

Quando uma execução termina, o runner encerra todos os processos que o agente deixou para trás, como um servidor de desenvolvimento.

O chaveiro no macOS

O sandbox do macOS não fecha por completo o chaveiro. Por isso, não guarde nenhum login do GitHub no chaveiro do usuário que executa o runner (o init avisa quando encontra um). A configuração mais segura é um usuário dedicado do macOS, com chaveiro próprio.

Windows

O Windows puro não tem sandbox de shell. O texto de um comentário poderia então fazer uma execução rodar qualquer comando em seu nome. Execute o runner dentro do WSL2. No Windows puro, o runner não inicia, a menos que você adicione "allowUnsandboxed": true ao config.json dele; faça isso apenas em uma máquina que não guarde mais nada.

Várias execuções ao mesmo tempo

No cartão Runners, você define Execuções em simultâneo: de 1 a 3. Cada execução usa o seu plano do Claude, então mantenha o número dentro do que o plano comporta. Um projeto nunca é executado duas vezes ao mesmo tempo: uma segunda execução no mesmo projeto espera a primeira.

Cada execução simultânea tem a própria pasta de slot. A sandbox de uma execução não consegue ler os outros slots.

Um runner para um cliente

Ao criar um runner, você pode limitá-lo a um espaço de trabalho em Executa para. Ele passa a pegar apenas as execuções desse cliente. Para configurá-lo no computador do cliente: instale o Claude Code lá, execute npx @notiamo/runner init e cole o token do runner. O login do Claude naquele computador paga as execuções, então entre com a conta que deve pagar.

Comandos de preparação e de teste

Um clone limpo não tem pacotes instalados. Diga ao agente como instalá-los e como testar. Abra as configurações do agente do projeto e preencha Comando de preparação e Comando de teste, uma linha cada.

  • O agente executa o comando de preparação uma vez, antes da sua primeira alteração. Exemplo: pnpm install --frozen-lockfile.
  • O agente executa o comando de teste antes de cada commit. Uma alteração que falha nele é corrigida ou desfeita. Exemplo: pnpm typecheck && pnpm lint.
  • O agente executa os dois por conta própria, na mesma sandbox dos seus outros comandos. O registro de pacotes precisa estar entre os hosts permitidos. O GitHub e o registry.npmjs.org estão lá por padrão. Adicione qualquer outro (PyPI, crates.io, um registro privado) em Hosts adicionais que o agente pode aceder, no cartão Runners.
  • Cada projeto tem uma pasta de cache de pacotes ao lado do seu clone. npm, pnpm, Yarn, Corepack, Bun, pip, uv e Composer guardam seus caches ali, porque a sandbox fecha os lugares habituais da sua pasta pessoal. A pasta permanece entre as execuções do projeto e some com o clone. Ela não existe no Windows puro.
  • Mantenha o comando de teste leve. Um teste que precisa do Docker não consegue executar. Um teste que precisa de um banco de dados só executa quando o arquivo env do projeto aponta para um que você mantém em funcionamento (veja abaixo).

O agente faz commits como “Notiamo agent”, uma linha simples por item. O runner desativa o trailer “Co-Authored-By” e a linha “Generated with” do Claude Code, para que o repositório não mostre nenhum coautor de IA.

Um ambiente para os seus próprios projetos

Uma execução em um projeto do GitHub recebe um clone limpo e nada mais. Em um projeto de software seu, os testes também podem precisar de um banco de dados, de um armazenamento de arquivos, de um capturador de e-mails e de um .env. A máquina do runner os entrega às execuções de um projeto com um arquivo simples:

npx @notiamo/runner env <projectId>

<projectId> é a última parte do endereço da página do projeto no Notiamo. O comando cria ~/.notiamo-runner/env/<projectId>.env, legível só por você, e mostra o caminho. Coloque um KEY=VALUE por linha. A próxima execução desse projeto recebe as variáveis no seu shell, e o agente é informado dos nomes delas, nunca dos valores. Remova o arquivo para tirá-las. O arquivo nunca sai da máquina: o Notiamo não sabe que ele existe.

Com o arquivo presente, o shell da execução também pode alcançar serviços em 127.0.0.1 no macOS: o seu Postgres, um armazenamento de arquivos, um servidor de desenvolvimento. Você os mantém em funcionamento; o agente não consegue iniciá-los, e o Docker fica fora do alcance dele. No Linux, a sandbox tem a própria rede, então o 127.0.0.1 de lá não é o da máquina: associe os serviços ao endereço de rede da máquina e adicione esse host em Hosts adicionais que o agente pode aceder.

Regras:

  • Só valores de desenvolvimento e de teste. O agente executa comandos de shell e pode ler todas as variáveis. Nunca uma chave de produção, nunca uma senha que você usa em outro lugar.
  • PATH, HOME, as variáveis de proxy e de certificado, NODE_OPTIONS, NODE_TLS_REJECT_UNAUTHORIZED, NOTIAMO_*, GIT_*, CLAUDE_* e ANTHROPIC_* são ignoradas, e o log avisa isso. O arquivo pode mudar o que os comandos do agente enxergam, nunca como o Claude Code conversa com a Anthropic e o Notiamo.
  • Valores de 6 caracteres ou mais são mascarados como [secret] na transcrição que o Notiamo recebe. Valores curtos (1, true) não são.
  • Mantenha Execuções em simultâneo em 1 quando os projetos de um runner compartilham um banco de dados pelo arquivo env. Duas execuções ao mesmo tempo rodariam seus testes no mesmo banco.

Sites WordPress

A conexão fica no cartão Acesso ao site do projeto: uma senha de aplicativo e, opcionalmente, SSH ou FTP. O runner guarda a chave do servidor SSH na primeira visita e recusa um servidor que mostre outra chave depois. Uma execução funciona assim:

  1. Backup antes. Com SSH, o runner exporta o banco de dados e o envia ao Notiamo, compactado, com no máximo 200 MB. O Notiamo o mantém por 30 dias. Só com FTP ou com a API, não há backup.
  2. O agente trabalha dentro da lista de permissões abaixo.
  3. Verificação do site depois. O runner abre o site e confere se ele ainda responde.
  4. Restauração em caso de falha. Se a verificação falha, o runner restaura o banco de dados.

O que o agente pode executar com o wp-cli, por grupo (definido no projeto):

  • Conteúdo: post *, term *, menu *, media import, option get, option update.
  • Base de dados: search-replace (apenas o texto antigo e o novo; nunca toca nas tabelas de usuários nem de opções), cache flush, rewrite flush, transient delete.
  • Plugins e temas: plugin e theme com list, activate, deactivate, update.
  • Informações: core version, site list, db size.
  • Arquivos: nenhum comando do wp-cli; o agente usa as suas ferramentas de arquivo. Elas escrevem estilos, scripts e outros arquivos que o servidor não executa.
  • Arquivos PHP (desativado por padrão): as ferramentas de arquivo também podem escrever PHP. Um arquivo PHP é código que roda no seu servidor, e uma execução de WordPress não tem etapa de aprovação: a alteração entra no ar na hora. Ative isso apenas em um site em que você confia em todas as pessoas que podem escrever um comentário.
  • Nunca, a menos que você escolha “Permitir tudo”: eval, eval-file, shell, user *, db query|import|reset|drop|export, plugin install, theme install, core update|download.

O que fica guardado onde

Tudo fica em ~/.notiamo-runner.

Caminho O que guarda
config.json O endereço do Notiamo, o nome do runner e o token do runner. Legível só por você.
claude/ A pasta de configuração do Claude Code para o runner: o login e as sessões dele.
projects/ As cópias de trabalho dos seus projetos, uma pasta por projeto em cada slot. Um projeto não usado pelo número de dias definido no cartão Runners é removido; a próxima execução o clona de novo.
git/ As cópias próprias do runner dos seus repositórios. O agente não pode ler nem escrever nesta pasta.
env/ Os arquivos env que você criou, um por projeto.
runs/ As configurações do Claude Code de cada execução em andamento. Nenhum segredo. Apagadas quando a execução termina.
runner.log O que o runner fez, sem segredos.
state.json Os ids das execuções em andamento. Depois de uma reinicialização, cada uma é informada ao Notiamo como falha.

Os segredos de uma execução (senhas do WordPress, os tokens da própria execução) vêm do Notiamo junto com a execução e ficam apenas na memória. O agente os recebe como variáveis de ambiente, nunca em um arquivo. O que o agente imprime é limpo deles antes de a transcrição ser enviada.

O runner nunca usa as credenciais git da máquina. Cada execução recebe do Notiamo um token do GitHub que vale por uma hora e apenas para o repositório da execução. O runner o guarda na memória e o usa para o próprio fetch e push. O Notiamo abre e faz o merge do pull request.

Parar um runner

No cartão Runners, clique em Desativar para pausar um runner ou em Excluir para removê-lo. O token de um runner excluído deixa de funcionar na hora.