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
claudeque 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:
bubblewrapesocat(Debian ou Ubuntu:sudo apt install bubblewrap socat). No macOS não há mais nada para instalar.
Depois:
- 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.
- Na máquina, execute:
npx @notiamo/runner init
- Cole o token. O
initverifica se o Claude Code funciona, executa o login do Claude Code para o runner, instala o serviço e o inicia. - 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/hookse o.git/configda 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.orgestã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_*eANTHROPIC_*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:
- 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.
- O agente trabalha dentro da lista de permissões abaixo.
- Verificação do site depois. O runner abre o site e confere se ele ainda responde.
- 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:
pluginethemecomlist,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.