Guia de configuração do AgentVera Runner

O que o Runner faz

Use o Runner quando quiser que os agentes rodem num servidor potente e sempre ligado, em vez do seu notebook. O Runner mantém as sessões de terminal dos agentes nesse servidor; feche a tampa, perca a conexão ou conecte-se de outro computador e a sessão continua.

• O código e as conversas ficam no seu servidor.
• A conexão é retransmitida pelo servidor do AgentVera via TLS criptografado; o tráfego de terminal retransmitido não é interpretado, registrado nem guardado lá.
• Você vê o uso de CPU, memória e disco do servidor, as sessões abertas e os arquivos das pastas que você permitir.
• Para tarefas que vêm de webhooks ou do “Send to agent” na web, o final da saída do agente (até 6.000 caracteres) é informado ao servidor como resumo da tarefa quando o turno termina.

Requisitos

• Um servidor ou computador com Linux ou macOS.
• Node.js 20 ou mais recente, e npm.
• curl ou wget.
• Para sessões de agente, uma CLI instalada e com login feito nesse servidor: Claude Code, Codex, Gemini CLI ou opencode. Sessões de terminal sempre funcionam.
• Uma organização AgentVera no plano Pro ou Team.

Se faltar o Node.js, instale pelo nodejs.org ou com o fnm:

curl -fsSL https://fnm.vercel.app/install | bash && fnm install 22

Para instalar o Claude Code e fazer login uma vez:

npm install -g @anthropic-ai/claude-code
claude login

Instalação

1. Abra app.agentvera.dev/runners no navegador e clique em “Yeni runner ekle” (adicionar runner). Aparece um código de pareamento de 8 caracteres, válido por 10 minutos.
2. Rode o comando abaixo no seu servidor, trocando KOD pelo seu código de pareamento.
3. Em segundos o runner aparece como online em /runners. Abra-o para ver o uso de CPU, memória e disco e iniciar uma sessão Claude, Codex ou de terminal com “Yeni ajan” (novo agente).

curl -fsSL https://app.agentvera.dev/runner/install.sh | sh -s -- --pair KOD

Se o código de pareamento expirou, basta criar um novo em /runners.

Opções do instalador

Adicione estas opções ao comando de instalação:

• --name NOME: o nome do runner. O padrão é o hostname da máquina.
• --server URL: o servidor do AgentVera. O padrão é https://app.agentvera.dev.
• --no-service: não instala um serviço em segundo plano, caso você só vá usar o runner pelo app desktop via SSH.

curl -fsSL https://app.agentvera.dev/runner/install.sh | sh -s -- --pair KOD --name build-server

O que o instalador faz

• Instala o Runner em ~/.agentvera-runner/app (uma pasta que só você abre) e cria o link do comando como ~/.local/bin/agentvera-runner.
• No Linux com systemd, cria um serviço de usuário chamado agentvera-runner que se reinicia sozinho se parar.
• Sem systemd, o Runner inicia em segundo plano e grava logs em ~/.agentvera-runner/runner.log; depois que o servidor reinicia, você o inicia de novo na mão.
• No macOS, instala um agente launchd chamado dev.agentvera.runner que inicia no login, se reinicia se parar e grava logs em ~/.agentvera-runner/runner.log.
• Salva o token de acesso num arquivo que só você pode ler.

No Linux, para manter o Runner rodando depois que você sai da sessão, rode isto uma vez:

sudo loginctl enable-linger $USER

Linha de comando

agentvera-runner status               # version, service, pairing, server and allowed folders
agentvera-runner roots ~/projects      # limit agents and file access to these folders
agentvera-runner pair KOD --name NAME  # pair again
agentvera-runner daemon                # run Runner in the foreground

Sem roots, os agentes trabalham na sua pasta pessoal. Depois de parear de novo, reinicie o serviço; o Runner se conecta ao iniciar.

Como gerenciar o serviço

Linux (systemd):

systemctl --user status agentvera-runner
systemctl --user restart agentvera-runner
systemctl --user stop agentvera-runner
journalctl --user -u agentvera-runner -f

macOS (launchd):

launchctl unload ~/Library/LaunchAgents/dev.agentvera.runner.plist   # stop
launchctl load -w ~/Library/LaunchAgents/dev.agentvera.runner.plist   # start
tail -f ~/.agentvera-runner/runner.log

Como conectar pelo app desktop

A página Runner do app desktop do AgentVera se conecta a runners de dois jeitos: pela nuvem, com a mesma conta, ou direto por um servidor SSH salvo. Se for usar SSH, você pode instalar com --no-service; o app inicia o Runner sozinho quando se conecta.

Como desinstalar

1. Exclua o runner em app.agentvera.dev/runners. O token dele é revogado na hora e ele para de se reconectar.
2. Pare e remova o serviço.
3. Apague os arquivos do Runner.

# Linux
systemctl --user disable --now agentvera-runner
rm ~/.config/systemd/user/agentvera-runner.service

# macOS
launchctl unload ~/Library/LaunchAgents/dev.agentvera.runner.plist
rm ~/Library/LaunchAgents/dev.agentvera.runner.plist

# both
rm -rf ~/.agentvera-runner ~/.local/bin/agentvera-runner

Segurança

• O Runner só abre conexões de saída; você não precisa abrir portas nem mexer no firewall.
• Só membros ativos da sua organização podem ver o runner e se conectar a ele. A equipe de suporte, ao visualizar como um usuário, não consegue se conectar.
• Conexões abertas são encerradas para usuários cuja participação termina ou cuja organização é suspensa.
• Use roots para decidir a quais pastas os agentes e o acesso a arquivos ficam limitados.
• Tarefas disparadas por webhooks podem enviar prompts ao runner; conecte só origens em que você confia.

Solução de problemas

• “Node.js 20 ya da üstü gerekli” (é necessário Node.js 20 ou mais recente): instale o Node.js 22 e rode o comando de novo.
• Código de pareamento inválido: os 10 minutos podem ter acabado; gere um novo código em /runners.
• O runner não aparece como online: confira a saída de agentvera-runner status e os logs; garanta que o servidor alcança app.agentvera.dev:443.
• Falta um tipo de agente em “Yeni ajan”: instale aquela CLI no servidor e faça login; o Runner só lista os agentes que encontra instalados.