Documentação

Como funciona

O LeafAgents tem três partes. Você só instala uma delas, o runner, e só se quiser usar as assinaturas que já paga (Claude, ChatGPT, Gemini…).

• O runner abre uma conexão de saída pra nuvem. Não precisa abrir porta, configurar roteador nem certificado.
• O login dos CLIs (a sua assinatura) nunca sai da máquina onde o runner roda.
• Cada agente escolhe de quem é a credencial: assinatura (runner), api key (sua chave, na nuvem) ou crédito LeafAgents. Um mesmo fluxo pode misturar os três.

Começar em 5 minutos

1. Entre na sua contaAcesse app.leafagents.com.br.
2. Tenha pelo menos um CLI de IA logadoClaude Code, Codex, OpenCode ou Gemini CLI. Veja como.
3. Instale o app LeafAgents e entre com a contaEle fica na bandeja e conecta este computador. Passo a passo.
4. Crie um agente e mande uma mensagemNo canvas, escolha o agente, deixe a cobrança em assinatura e converse. Como usar.

1. Instale os CLIs de IA

O runner usa os CLIs oficiais que já estão na máquina. Instale os que você assina e faça login uma vez em cada um. Os comandos de instalação pelo npm pedem o Node.js. O Claude Code e o OpenCode também têm instaladores próprios, que dispensam o Node. Veja o site de cada um.

2. Conecte pelo app desktop

É o jeito recomendado num computador com tela. O app abre junto com o sistema, fica na bandeja (perto do relógio) e se atualiza sozinho.

1. Baixe e instaleEm leafagents.com.br/#baixar: .exe no Windows, .zip no macOS (Apple Silicon ou Intel), AppImage ou .deb no Linux.
2. Abra o app e clique em “Entrar com a conta LeafAgents”O navegador abre na página de autorização. Se você não estiver logado, entre primeiro.
3. Confira o código e clique em “Conectar”A página mostra um código de 6 caracteres. Ele precisa ser igual ao que aparece no app. Se for diferente, ou se você não pediu, clique em Recusar.
4. ProntoO app mostra Conectado, a sua conta e os CLIs que encontrou. Pode fechar a janela: o LeafAgents continua rodando na bandeja.

Primeira abertura

O app ainda não tem assinatura de código da Microsoft e da Apple, então o sistema pede uma confirmação na primeira vez:

• Windows: se aparecer “O Windows protegeu o computador”, clique em Mais informações → Executar assim mesmo. Em computadores com Windows ARM, o app roda emulado normalmente.
• macOS: descompacte o .zip, arraste o LeafAgents para Aplicativos e abra. Se o macOS bloquear, vá em Ajustes do Sistema → Privacidade e Segurança e clique em Abrir mesmo assim. Precisa do macOS 13 (Ventura) ou mais novo.
• Linux (AppImage): há versões para x64 e ARM64. Dê permissão de execução (chmod +x LeafAgents-x86_64.AppImage) e abra. No GNOME, o ícone da bandeja aparece só com a extensão AppIndicator. Sem ela, abra o app de novo pelo menu para ver a janela.

O que tem na janela

• Status: Conectado, Conectando, Em espera (outro runner assumiu a conta) ou Não conectado.
• CLIs neste computador: quais foram encontrados e as versões. Instalou um agora? Clique em Verificar de novo.
• Abrir ao iniciar o computador: ligado depois do primeiro login. O app abre escondido, só na bandeja.
• Permitir editar arquivos e rodar comandos: desligado por padrão. Veja Arquivos e comandos.
• Sair da conta neste computador: apaga o login daqui. Para revogar de vez, remova o computador em Conexões.

Conectar pelo terminal

Prefere o terminal, ou está num servidor sem tela? Instale o runner como um executável único. Não precisa de Node.

curl -fsSL https://leafagents.com.br/install.sh | sh

irm https://leafagents.com.br/install.ps1 | iex

O instalador coloca o leafagents-runner em ~/.leafagents/bin (no Windows, %LOCALAPPDATA%\LeafAgents\bin) e adiciona a pasta ao PATH. Abra um terminal novo e rode:

leafagents-runner

Na primeira vez ele mostra um link e um código de conferência e abre o navegador. Aprove do mesmo jeito que no app. Depois disso ele conecta sozinho. Deixe o terminal aberto enquanto usa os agentes (Ctrl+C encerra).

Rodar numa VPS

Com o runner num servidor, os agentes de assinatura ficam disponíveis 24 horas, mesmo com o seu computador desligado. O runner numa VPS própria faz parte dos planos Pro e Max. No Free, o runner precisa estar no seu computador, na mesma rede do navegador: um runner em outra rede conecta, mas não atende os agentes.

1. Instale os CLIs, como administradorComo na tabela acima. Com o Node.js do sistema, o npm i -g precisa de sudo.

   sudo npm i -g @anthropic-ai/claude-code @openai/codex opencode-ai

   Copiar
2. Crie um usuário para o runner e entre neleEvite rodar como root: os agentes trabalham com as permissões desse usuário.

   sudo adduser leaf
   sudo -iu leaf

   Copiar
3. Faça login nos CLIs, como esse usuárioSem navegador no servidor, os CLIs mostram um link: abra no seu computador e cole o código de volta no terminal da VPS.

   claude          # siga o login e saia com /exit
   codex login
   opencode auth login

   Copiar
4. Instale o runner

   curl -fsSL https://leafagents.com.br/install.sh | sh
   source ~/.bashrc
   leafagents-runner doctor   # confira se os CLIs aparecem

   Copiar
5. Autorize a VPS na sua contaO comando mostra um link e um código. Abra o link no seu computador, logado no LeafAgents, confira o código e clique em Conectar.

   leafagents-runner login

   Copiar
6. Deixe rodandoComo um serviço do sistema, para reiniciar sozinho com a VPS. Veja abaixo.
7. Confira no app webEm Conexões deve aparecer Conectado com o nome da VPS.

Deixar rodando com systemd

Antes, como leaf, rode which claude codex opencode e confira se as pastas aparecem no PATH do serviço abaixo. Depois saia do usuário (exit) e crie o serviço como administrador.

[Unit]
Description=LeafAgents runner
After=network-online.target
Wants=network-online.target

[Service]
User=leaf
WorkingDirectory=/home/leaf
ExecStart=/home/leaf/.leafagents/bin/leafagents-runner
Environment=PATH=/home/leaf/.local/bin:/home/leaf/.npm-global/bin:/usr/local/bin:/usr/bin:/bin
Restart=on-failure
RestartSec=10
# 78 = precisa de login (acesso revogado): não adianta reiniciar
RestartPreventExitStatus=78

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now leafagents-runner
journalctl -u leafagents-runner -f   # acompanhar o log

Sem login feito, o serviço não fica esperando: ele sai com uma mensagem pedindo leafagents-runner login.

Atualizar

sudo -u leaf /home/leaf/.leafagents/bin/leafagents-runner update
sudo systemctl restart leafagents-runner

Sem systemd

Num ambiente sem systemd, rode dentro do tmux: tmux new -s leaf, depois leafagents-runner, e saia com Ctrl+B D. Para voltar: tmux attach -t leaf.

3. Use no app web

Com o runner conectado, tudo acontece em app.leafagents.com.br, de qualquer navegador (Chrome, Safari, Firefox, Edge) e sem instalar nada nele.

Conexões

Clique em Conexões na barra lateral. Na parte Seu computador · assinatura você vê:

• Status: Conectado: nome-do-computador · sistema · desde 14:32, ou Nenhum computador conectado agora.
• Baixar o app e o comando de instalação pelo terminal, para conectar outro computador.
• Computadores autorizados: todos os computadores e VPS que já entraram na conta. O ícone de lixeira revoga o acesso na hora, e o runner daquele computador é desconectado.

Na mesma janela ficam as Chaves de API (Pro e Max) e o saldo do crédito LeafAgents.

Agentes e cobrança

No canvas, clique num agente para abrir o painel dele. Em Cobrança você escolhe de quem é a credencial:

Ligue os agentes com setas no canvas para a tarefa seguir de um para o outro, ou chame um agente direto com @Nome na conversa. O limite de agentes trabalhando ao mesmo tempo depende do plano. Os que passam do limite esperam na fila.

A conversa de cada agente de assinatura continua entre as mensagens, mesmo se o runner reiniciar. O runner guarda a sessão de cada CLI por thread. O Gemini CLI ainda começa do zero a cada mensagem.

Vários navegadores

• Free: o runner atende um navegador por vez, o mesmo em que você autorizou o login. Em outro navegador, Conexões mostra Usar o runner neste navegador. Ao clicar, o anterior deixa de ser atendido. Dá pra trocar de navegador até 3 vezes a cada 24 horas.
• Pro e Max: qualquer navegador logado na conta usa o runner ao mesmo tempo (notebook, desktop, celular).

Arquivos e comandos

Cada agente trabalha numa pasta própria na máquina do runner: ~/.leafagents/workspaces/<projeto>/<agente>. Por segurança, nenhum agente edita arquivos nem roda comandos até que duas coisas estejam ligadas:

1. no app web, em Permissões (tools) do agente: Escrever arquivos e/ou Shell;
2. na máquina do runner: Permitir editar arquivos e rodar comandos no app desktop, ou a opção --allow-dangerous no terminal (leafagents-runner --allow-dangerous; no systemd, no fim do ExecStart).

A segunda trava fica só na sua máquina: nem o app web nem a nuvem conseguem ligá-la.

Screenshots

A ferramenta Screenshot abre a página num navegador sem janela, na máquina do runner, e anexa a imagem à conversa. O runner usa o Google Chrome, o Chromium, o Edge ou o Brave que já estiverem instalados.

• No Windows, o Edge já vem instalado e serve.
• Numa VPS Debian/Ubuntu: sudo apt install -y chromium (no Ubuntu pode vir como snap, que também funciona).
• Se o navegador estiver em outro lugar, informe o caminho em LEAFAGENTS_CHROMIUM ou com --chromium /caminho/do/chrome.

Planos

O crédito é uma carteira em reais que vale em qualquer plano. A recarga mínima é de R$ 25 e o saldo não expira. O crédito incluso do Max é usado primeiro e volta para R$ 40 todo mês, sem acumular. Veja os preços por modelo em Planos.

Segurança e privacidade

• A sua assinatura fica com você. O login do Claude Code, do Codex e dos outros CLIs nunca sai da máquina do runner.
• Prompts e respostas passam pela nuvem LeafAgents só para chegar ao navegador. O repasse não guarda o conteúdo. Os projetos e threads ficam salvos na sua conta (Pro e Max) para sincronizar entre dispositivos.
• Cada computador tem um acesso próprio, criado na autorização pelo navegador. Ele fica em ~/.leafagents/runner.json, e no servidor só guardamos uma impressão (hash) dele.
• Revogue quando quiser: em Conexões → Computadores autorizados. O runner é desconectado na hora.
• Chaves de API ficam cifradas na sua conta, nunca voltam para o navegador (só os 4 últimos caracteres) e podem ser removidas a qualquer momento.
• Arquivos e comandos exigem a sua permissão na própria máquina do runner (veja acima).
• O runner não abre portas. Ele só se conecta de saída à nuvem, por HTTPS.

Solução de problemas

Comandos do runner

Opções do start