Para rodar o Claude Code em um servidor remoto, instale-o no servidor, faça login uma vez e inicie-o dentro de uma sessão de terminal que sobrevive à sua desconexão, geralmente tmux via SSH. Essa é a ideia toda. O resto é escolher onde o servidor fica, como o agente faz login sem navegador e quanto do seu mundo o agente consegue alcançar a partir dali.
Este post explica por que as pessoas levam agentes para uma VPS, compara as configurações mais comuns, mostra como fazer login em uma máquina sem tela e o básico de segurança, e depois mostra como o AgentVera lida com agentes remotos com Runner, agentes via SSH e Docker.
Por que rodar um agente de código em um servidor remoto
Um notebook é uma casa ruim para execuções longas de agentes. Ele entra em suspensão, perde o Wi-Fi e você fecha a tampa para ir para casa. Um servidor não.
Motivos comuns para tirar os agentes da sua máquina:
- Tarefas longas. Uma migração, uma grande refatoração ou uma suíte de testes que leva uma hora não deveria parar porque seu notebook entrou em suspensão.
- O código já está lá. Alguns projetos só compilam no Linux, precisam de GPU ou de um banco de dados que só existe naquela rede.
- Isolamento. Um agente em uma VM descartável não consegue tocar nos seus arquivos pessoais, chaves SSH ou sessões do navegador.
- Acesso de qualquer lugar. Você inicia uma tarefa na sua mesa e acompanha de outro computador ou do celular.
- Vários agentes ao mesmo tempo. Um servidor com mais núcleos e memória roda mais agentes em paralelo que um notebook.
A contrapartida é configuração e responsabilidade. Um servidor que você controla é um servidor que você precisa proteger.
As opções em resumo
| Configuração | Sobrevive à desconexão | Isolamento | Esforço | Bom para |
|---|---|---|---|---|
| SSH + tmux em uma VPS | Sim | Máquina separada | Baixo | A maioria das pessoas, um ou dois projetos |
| Dev container (local ou remoto) | Enquanto o contêiner roda | Contêiner | Médio | Ambientes reproduzíveis, equipes |
| VM na nuvem por tarefa | Sim | VM completa | Médio a alto | Ambientes descartáveis, trabalho arriscado |
| Agente em um contêiner na sua máquina | Não, para junto com o agente | Contêiner | Baixo | Isolamento sem servidor |
SSH e tmux
Esta é a configuração mais simples e funciona com qualquer agente de CLI. No servidor:
npm install -g @anthropic-ai/claude-code
tmux new -s agent
cd ~/projects/my-app
claudeDesanexe com Ctrl-b d e feche o SSH. O agente continua trabalhando. Depois, conecte de novo com ssh e rode tmux attach -t agent. Se você prefere screen ou zellij, a ideia é a mesma: a sessão pertence ao servidor, não à sua conexão SSH.
O que você perde: não há árvore de arquivos, nem visualização de diff, e alternar entre vários agentes significa fazer malabarismo com janelas do tmux.
Dev containers
Um dev container descreve o ambiente em um arquivo (devcontainer.json mais um Dockerfile), então toda máquina recebe as mesmas ferramentas. Você pode rodá-lo localmente ou em um host Docker remoto. O agente roda dentro do contêiner e vê só o que você monta nele.
O porém é que o login do agente também precisa existir dentro do contêiner, e um contêiner reconstruído perde tudo o que você não persistiu.
VMs na nuvem
Uma VM nova por tarefa dá o isolamento mais limpo: se o agente estragar algo, você apaga a máquina. Exige mais configuração, e você precisa de um jeito de levar o código para dentro e tirar o resultado, geralmente uma branch que o agente envia.
Login em uma máquina sem tela
Agentes de código normalmente fazem login pelo navegador. Um servidor não tem navegador, então você precisa de um destes caminhos.
Claude Code
- Navegador no seu computador. Rode
claudeno servidor. Ele mostra um link de login; abra no seu próprio computador. Se o navegador não conseguir alcançar o callback local do servidor, o Claude Code mostra um código para colar no prompt “Paste code here if prompted” do terminal. - Token de longa duração.
claude setup-tokencria um token OAuth de um ano para uma assinatura Pro, Max, Team ou Enterprise. Ele não é salvo em lugar nenhum por você: defina-o no servidor comoCLAUDE_CODE_OAUTH_TOKEN. Esse token cobre só as requisições ao modelo. - Chave de API. Defina
ANTHROPIC_API_KEYse você paga por uso pela API.
No Linux, o Claude Code guarda as credenciais em ~/.claude/.credentials.json com permissão de arquivo 0600. No macOS elas vão para o Keychain e, via SSH, ele recorre a esse arquivo se o Keychain estiver bloqueado.
Codex
- Código de dispositivo.
codex login --device-authdá um código para você digitar em um navegador em outro lugar. Está em beta e precisa ser ativado nas configurações de segurança do ChatGPT (ou pelo administrador do seu workspace). - Chave de API.
printenv OPENAI_API_KEY | codex login --with-api-key. - Alternativas. Copie
~/.codex/auth.jsonde uma máquina onde você está logado, ou encaminhe a porta de login comssh -L 1455:localhost:1455e faça login normalmente.
Seja qual for o caminho, um arquivo de credenciais em um servidor é tão sensível quanto uma senha. Quem conseguir lê-lo pode usar sua assinatura.
Segurança no servidor
Um agente em um servidor roda comandos com os direitos do usuário com que ele roda. Planeje-se para isso.
- Use um usuário separado. Não rode agentes como root. Um usuário dedicado com sua própria pasta pessoal limita o que um comando ruim consegue alcançar.
- Mantenha segredos de produção fora da máquina. Se o agente não precisa da senha do banco de produção, ela não deveria estar em um arquivo
.envnaquele servidor. - Feche as portas de entrada. SSH só com chaves, sem login por senha e sem servidores de desenvolvimento expostos que você esqueceu.
- Trabalhe em branches. Deixe o agente enviar para uma branch, não para a main. Git worktrees permitem que vários agentes trabalhem no mesmo repositório sem atrapalhar uns aos outros.
- Cuidado com tokens de longa duração. Um token de um ano em um servidor compartilhado é um risco de um ano. Troque-o se a máquina for compartilhada ou desativada.
- Conte com logins expirando. Em execuções sem supervisão, confira se a sessão ainda está logada antes de deixá-la sozinha durante a noite.
Como o AgentVera roda agentes em um servidor
O AgentVera é um app de desktop que roda CLIs de agentes de código lado a lado em terminais reais com seus próprios logins. Ele oferece três formas de tirar agentes da sua máquina.
Runner: seu próprio servidor, aberto de qualquer lugar
O Runner é um pequeno serviço que você instala no seu próprio servidor Linux ou macOS, ou em um Mac. Ele roda sessões de Claude Code, Codex, Gemini CLI, opencode e terminais comuns em terminais reais. As sessões continuam rodando quando você desconecta, e você reconecta pelo navegador ou pelo app de desktop.
A configuração, em resumo:
- Abra app.agentvera.dev/runners e adicione um runner. Você recebe um código de pareamento de 8 caracteres válido por 10 minutos.
- No servidor, rode o comando de instalação com esse código:
curl -fsSL https://app.agentvera.dev/runner/install.sh | sh -s -- --pair KOD- Instale a CLI no servidor e faça login, por exemplo
npm install -g @anthropic-ai/claude-codee depoisclaude login.
O Runner precisa de Node.js 20 ou mais recente e de curl ou wget. No Linux, ele instala um serviço de usuário do systemd; rode sudo loginctl enable-linger $USER uma vez para que ele continue rodando quando você sair. Para manter os agentes dentro de certas pastas, rode agentvera-runner roots ~/projects. Sem roots, os agentes trabalham na sua pasta pessoal.
Quanto à segurança, o Runner só faz uma conexão de saída para app.agentvera.dev na porta 443, então você não abre nenhuma porta no servidor. O tráfego é retransmitido via TLS, e o servidor do AgentVera não interpreta, não registra e não armazena esse tráfego. Seu código fica no seu servidor, e só membros ativos da sua organização conseguem se conectar. A página do Runner também mostra CPU, memória e disco do servidor.
O Runner está nos planos Pro e Team.
Agentes via SSH: sem serviço extra
Se você já tem um servidor na lista de SSH do AgentVera, não precisa do Runner. Na janela de novo agente, defina Runs on como esse servidor salvo em vez de This computer, e escolha a Folder on the server. O agente então roda no servidor com o login de CLI do próprio servidor. Como a janela avisa, a CLI precisa estar instalada e logada no servidor, ou você pode fazer login pelo terminal do agente na primeira execução. Suas contas locais e suas configurações de MCP e navegador não são usadas no servidor.
Se o tmux estiver instalado no servidor, o AgentVera inicia o agente dentro de uma sessão tmux. Essa sessão sobrevive à conexão SSH, e a próxima conexão, de qualquer computador, se anexa a ela de novo. Fechar o app não a interrompe; parar ou fechar o agente, sim.
O recurso de SSH em si é gratuito: servidores salvos, um cofre criptografado para credenciais, SFTP e ProxyJump. Os detalhes estão na página SSH e SFTP.
Agentes em um contêiner Docker: isolamento sem servidor
Às vezes você não precisa de um servidor, precisa de um muro. Para um agente local de Claude Code ou Codex, ative Run in a Docker container na janela do agente. O agente vê só a pasta do projeto; outros arquivos, programas e chaves SSH do seu computador ficam fechados para ele. Você pode definir limites de CPU e memória.
O AgentVera cria a própria imagem (Node 22, git, ripgrep, Claude Code e Codex) no primeiro uso, ou você pode usar sua própria imagem, desde que ela tenha o comando claude ou codex. O contêiner é removido quando o agente para. É preciso ter Docker Desktop, Colima ou OrbStack. Isso é gratuito; veja agentes no Docker.
Qual escolher
| Você quer | Use |
|---|---|
| Agentes que rodam por horas no seu servidor, abertos pelo navegador | Runner (Pro e Team) |
| Um agente em um servidor que você já acessa via SSH | Runs on → servidor SSH salvo |
| Isolamento na sua própria máquina | Run in a Docker container |
| Uma olhada rápida em um agente rodando, pelo celular | O app para celular ou o Telegram |
Erros comuns
- Iniciar o agente direto na sessão SSH e perdê-lo quando a conexão cai.
- Rodar o agente como root “só por enquanto”.
- Copiar para o servidor um
.envinteiro com chaves de produção. - Deixar um token de longa duração em uma máquina compartilhada e esquecer dele.
- Deixar vários agentes trabalharem na mesma pasta em vez de branches ou worktrees separados.
Checklist
- A CLI está instalada e logada no servidor.
- O agente roda dentro do tmux, do Runner ou de outra sessão que sobrevive a uma desconexão.
- Ele roda como um usuário que não é root, limitado às pastas do projeto.
- Nenhum segredo de produção fica no servidor, a menos que a tarefa precise.
- As portas de entrada estão fechadas, exceto SSH com chaves.
- Cada agente trabalha na sua própria branch ou worktree.
Conclusão
Rodar o Claude Code em um servidor remoto se resume a três coisas: uma sessão que sobrevive à sua conexão, um login que funciona sem navegador e um servidor que guarda só o que o agente precisa. SSH e tmux resolvem isso em cinco minutos. Se você quer iniciar agentes de qualquer lugar, ver seus arquivos e diffs e manter vários rodando ao mesmo tempo, o Runner e os agentes via SSH do AgentVera fazem o mesmo trabalho com menos malabarismo.
Leia mais:
- Git worktree para agentes em paralelo
- Crie um bot de trading de cripto com IA
- Rode vários agentes do Claude Code
- Docker
- O que é um agente de código?
Para experimentar o AgentVera, comece pela página inicial.