Claude Code num VPS

Problema: Claude Code parece natural no teu laptop, mas um servidor remoto parece outro desporto. Talvez queiras que esteja disponível 24/7 para tarefas longas. Talvez precises que seja acessível de várias máquinas sem arrastar ambientes. Ou simplesmente queres tirar o trabalho pesado de IA da bateria do teu laptop.

Correr Claude Code num VPS é simples quando tens os detalhes claros: SSH, Node.js, autenticação e Docker para isolamento (opcional). Este guia percorre toda a configuração com comandos reais que podes colar num Ubuntu novo.

Escolher um VPS e o que Precisas

Claude Code precisa de mais recursos do que uma app Node típica. O modelo em si corre nos servidores da Anthropic, mas o processo local ainda gere o contexto, operações de ficheiros e execução de ferramentas.

Especificações mínimas do VPS:

• 2 vCPUs (4 recomendadas para workloads multi-agente)
• 4 GB RAM (8 GB recomendados)
• 40 GB de armazenamento SSD
• Ubuntu 22.04 ou 24.04 LTS

Fornecedores que funcionam bem: Qualquer grande fornecedor de VPS resolve isto sem drama. AWS Lightsail, DigitalOcean, Hetzner e Linode têm planos de $10-20/mês que cumprem estas especificações. O Hetzner ganha na relação preço-desempenho para devs europeus. O Lightsail é o mais fácil se já vives dentro da AWS.

O que ter antes de começar:

• Uma chave de API da Anthropic (em console.anthropic.com) ou uma subscrição Pro/Max
• Acesso SSH ao servidor
• Um nome de domínio (opcional, para acesso por Remote Control)

Configuração SSH e Acesso Seguro

Começa com um servidor Ubuntu vazio. A maioria dos fornecedores coloca-te como root com password. O primeiro trabalho é bloquear o acesso.

# Ligar ao teu novo servidor
ssh root@your-server-ip
 
# Criar um utilizador não-root
adduser deploy
usermod -aG sudo deploy
 
# Configurar autenticação por chave SSH
mkdir -p /home/deploy/.ssh
# Copia a tua chave pública (corre isto na tua máquina LOCAL):
# ssh-copy-id deploy@your-server-ip
 
# Desativar autenticação por password
sudo sed -i 's/#PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
sudo sed -i 's/PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
sudo systemctl restart sshd

Configura uma firewall básica antes de instalar qualquer coisa:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

A partir daqui, liga-te sempre como utilizador não-root: ssh deploy@your-server-ip.

Instalar Claude Code num Servidor Headless

Claude Code precisa de Node.js 18+. Usa o repositório NodeSource para o LTS atual:

# Instalar Node.js 22 LTS
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
 
# Verificar instalação
node --version  # Deve mostrar v22.x
npm --version
 
# Instalar Claude Code globalmente
npm install -g @anthropic-ai/claude-code
 
# Verificar Claude Code instalado
claude --version

Autenticação: Numa máquina headless sem browser, autenticas com uma chave de API.

# Definir a tua chave de API da Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
 
# Ou para sessões persistentes, adiciona ao teu perfil de shell
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
source ~/.bashrc

Tens uma subscrição Pro ou Max e queres usar OAuth? Corre claude uma vez, copia o URL de autenticação que aparece, abre-o num browser em qualquer dispositivo e cola o código de volta no terminal.

Correr Claude Code em Modo Não-Interativo

Num servidor, o modo útil é headless, não chat interativo. É aqui que a automação começa a fazer sentido.

Execução de comando único:

# Correr uma única tarefa e sair
claude -p "Review the codebase in /opt/apps/myproject and list any security issues"
 
# Passar input por pipe para processamento
cat error-log.txt | claude -p "Analyze these errors and suggest fixes"

A flag -p (modo print) corre Claude Code de forma não-interativa. Lê o prompt, imprime o resultado e sai. Sem UI de chat. Sem esperar por input.

Combinar com SSH para gestão remota: É aqui que um Claude Code hospedado num VPS começa a valer o investimento. Da tua máquina local:

# Correr Claude Code no teu servidor a partir do teu laptop
ssh deploy@your-server "cd /opt/apps/myproject && claude -p 'Run the test suite and fix any failures'"

Podes também usar Remote Control para entrar numa sessão interativa a partir do telemóvel ou outro dispositivo, o que ajuda a monitorizar execuções longas de agentes.

Fluxo de Trabalho com Docker

Docker adiciona isolamento e reprodutibilidade. Algo falha, destrói o contentor e lança um novo. Sem limpar um servidor poluído.

Cria um docker-compose.yml para o teu workspace de Claude Code:

version: "3.8"
services:
  claude-workspace:
    image: node:22-slim
    container_name: claude-code
    working_dir: /workspace
    volumes:
      - ./projects:/workspace
      - claude-cache:/home/node/.claude
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - NODE_ENV=production
    command: >
      bash -c "
        npm install -g @anthropic-ai/claude-code &&
        tail -f /dev/null
      "
    restart: unless-stopped
 
volumes:
  claude-cache:

Inicia o workspace e usa-o:

# Iniciar o contentor
docker compose up -d
 
# Executar Claude Code dentro do contentor
docker exec -it claude-code claude -p "List all files in the workspace"
 
# Abrir uma sessão interativa
docker exec -it claude-code claude
 
# Ver logs do contentor
docker logs claude-code

A linha tail -f /dev/null mantém o contentor vivo para poderes entrar nele quantas vezes quiseres. O volume claude-cache guarda os dados de autenticação e sessão do Claude entre reinícios do contentor.

Para contentores específicos de projeto, usa ficheiros compose separados por projeto. Cada um tem o seu ambiente isolado com apenas os ficheiros necessários montados.

Monitorização e Gestão de Logs

Sessões longas de Claude Code num VPS precisam de atenção. Um processo que falha silenciosamente às 3 da manhã não é algo que queiras.

Usa tmux ou screen para sessões que sobrevivem a desligamentos SSH:

# Iniciar uma nova sessão tmux
tmux new -s claude-session
 
# Correr Claude Code dentro do tmux
cd /opt/apps/myproject
claude
 
# Desanexar: Ctrl+B, depois D
# Reanexa mais tarde:
tmux attach -t claude-session

Serviço systemd para workers de Claude Code sempre disponíveis:

# /etc/systemd/system/claude-worker.service
[Unit]
Description=Claude Code Worker
After=network.target
 
[Service]
Type=simple
User=deploy
WorkingDirectory=/opt/apps/myproject
Environment=ANTHROPIC_API_KEY=sk-ant-...
ExecStart=/usr/bin/claude -p "Analyze /var/log/app.log for errors since the last check and write a summary to /opt/apps/myproject/issues/latest-report.md"
Restart=always
RestartSec=3600
 
[Install]
WantedBy=multi-user.target

sudo systemctl enable claude-worker
sudo systemctl start claude-worker
 
# Verificar estado
sudo systemctl status claude-worker
 
# Ver logs
journalctl -u claude-worker -f

Erros Comuns e Como Resolvê-los

"EACCES: permission denied, mkdir '/usr/lib/node_modules'"

Instalaste Node.js como root e agora o npm quer acesso de escrita para instalações globais. Resolve assim:

sudo chown -R $(whoami) /usr/lib/node_modules
# Ou melhor: usa um gestor de versões como nvm

"Error: Unable to open browser for authentication"

Normal numa máquina headless. Usa o método de chave de API acima, ou cola o URL de autenticação num browser noutro dispositivo.

Processo Claude Code morto por OOM (Out of Memory)

O teu VPS tem pouca RAM. Sessões multi-agente que lançam muitos sub-agentes consomem memória por agente. Soluções:

# Verificar uso atual de memória
free -h
 
# Adicionar swap se não tiveres
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

A ligação SSH cai durante sessões longas de Claude Code

Define keep-alive SSH na tua máquina local:

# ~/.ssh/config
Host your-server
    HostName your-server-ip
    User deploy
    ServerAliveInterval 60
    ServerAliveCountMax 3

Ou corre dentro do tmux (acima) para a sessão continuar mesmo que o SSH caia.

Considerações de Segurança

Correr um agente de codificação IA num servidor com credenciais reais exige cuidado extra.

Nunca faças commit de chaves de API. Usa variáveis de ambiente ou um gestor de segredos:

# Usa um ficheiro .env ignorado pelo git
echo "ANTHROPIC_API_KEY=sk-ant-..." > /opt/apps/myproject/.env
 
# Carregar no teu shell
set -a; source /opt/apps/myproject/.env; set +a

Restringe o acesso de ficheiros do Claude Code em tarefas automatizadas. A flag --sandbox limita o acesso ao filesystem e à rede:

claude --sandbox -p "Analyze this codebase for security issues"

Configura Fail2ban para bloquear tentativas de força bruta SSH:

sudo apt install fail2ban
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Mantém o servidor atualizado:

sudo apt update && sudo apt upgrade -y
sudo apt autoremove -y

O Que Vem a Seguir

Um Claude Code hospedado num VPS abre fluxos de trabalho que máquinas locais não conseguem: disponibilidade 24/7, tarefas agendadas que correm enquanto dormes e sessões multi-agente que não drenam a bateria do teu laptop. Combina com git worktrees para trabalho isolado em branches, ou usa Remote Control para controlar sessões do telemóvel.

Começa pequeno. Faz Claude Code correr num VPS básico via SSH. Adiciona Docker quando precisares de isolamento. Adiciona serviços systemd quando precisares de automação. Escala a partir daí.