MÓDULO 2.4

🖥️ Instalando em VPS

Configure Claude Code em um servidor remoto Ubuntu 22.04. Ideal para automações 24/7, trabalho remoto e pipelines de CI/CD.

6
Tópicos
30
Minutos
Intermediário
Nível
Prático
Tipo
1

☁️ Escolhendo uma VPS

Uma VPS (Virtual Private Server) permite rodar o Claude Code 24/7 sem depender do seu computador pessoal. Há opções gratuitas e pagas com excelente custo-benefício.

🆓 Opções Gratuitas

  • •
    Oracle Free Tier

    2 VMs gratuitas permanentes (1 vCPU, 1GB RAM cada). A melhor opção gratuita. Registre em cloud.oracle.com

  • •
    Google Cloud Free Tier

    1 VM e2-micro gratuita permanente (us-east1, us-west1, us-central1)

💰 Opções Pagas (custo-benefício)

  • •
    Hetzner

    ~€4/mês — CX11: 1 vCPU, 2GB RAM. Melhor custo-benefício na Europa

  • •
    DigitalOcean / Linode

    ~$6/mês — Droplet básico: 1 vCPU, 1GB RAM. Boa documentação

💡 Configuração mínima recomendada

Para o Claude Code: 1 vCPU, 1GB RAM, 10GB disco. Ubuntu 22.04 LTS é o sistema operacional recomendado. Evite CentOS 7 (EOL) e Ubuntu 18.04 (Node.js 18+ pode ter problemas).

2

🔒 Acessando via SSH

SSH (Secure Shell) é o protocolo padrão para acessar servidores Linux remotamente. Configurar chaves SSH é mais seguro que senhas e elimina a necessidade de digitar senha a cada conexão.

1

Gerar chave SSH (no seu computador local)

# Gerar par de chaves SSH (Linux/Mac)
ssh-keygen -t ed25519 -C "meu-email@exemplo.com"
# Pressione Enter para aceitar o caminho padrão
# Defina uma senha forte (ou Enter para sem senha)

# A chave pública fica em:
cat ~/.ssh/id_ed25519.pub
# Copie este conteúdo para a VPS
2

Conectar ao servidor

# Conexão básica via SSH
ssh usuario@IP_DA_VPS

# Exemplo com root (primeira conexão):
ssh root@192.168.1.100

# Criar atalho no ~/.ssh/config:
Host minha-vps
  HostName 192.168.1.100
  User ubuntu
  IdentityFile ~/.ssh/id_ed25519

# Após configurar, conecte assim:
ssh minha-vps
3

Configurações de segurança básicas

# No servidor, atualizar sistema
sudo apt update && sudo apt upgrade -y

# Criar usuário não-root (boa prática)
sudo adduser meuusuario
sudo usermod -aG sudo meuusuario

# Copiar chave SSH para novo usuário
sudo -u meuusuario mkdir /home/meuusuario/.ssh
sudo cp ~/.ssh/authorized_keys /home/meuusuario/.ssh/
sudo chown -R meuusuario:meuusuario /home/meuusuario/.ssh
3

🟢 Node.js no Servidor Ubuntu

Em servidores Ubuntu, o nvm é o método ideal. Instala no diretório do usuário sem root, evitando problemas de permissão e isolando o ambiente do sistema.

Setup completo do zero — Ubuntu 22.04

# 1. Atualizar sistema
sudo apt update && sudo apt upgrade -y

# 2. Instalar dependências básicas
sudo apt install -y curl git build-essential

# 3. Instalar nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 4. Carregar nvm na sessão atual
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 5. Instalar Node.js LTS
nvm install --lts
nvm use --lts
nvm alias default 'lts/*'

# 6. Verificar
node -v    # v20.x.x
npm -v     # 10.x.x
which node # /home/usuario/.nvm/versions/...
4

⬇️ Instalando Claude Code no Servidor

Em servidores sem interface gráfica, o Claude Code precisa ser autenticado via API key antes mesmo da primeira execução. Configure as variáveis de ambiente antes de instalar o pacote.

1

Instalar Claude Code

# Instalar Claude Code globalmente
npm install -g @anthropic-ai/claude-code

# Verificar instalação
claude --version
which claude
2

Configurar variáveis no .bashrc

# Abrir .bashrc para edição
nano ~/.bashrc

# Adicionar ao final:
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="sk-or-v1-SUA-CHAVE"

# Salvar (Ctrl+O, Enter, Ctrl+X) e aplicar:
source ~/.bashrc

# Verificar
echo $ANTHROPIC_AUTH_TOKEN

⚠️ Segurança: Nunca exponha a API key

  • ✗Nunca comite a API key em repositórios git
  • ✗Não adicione a chave em arquivos .env sem .gitignore configurado
  • ✓Use variáveis de ambiente no sistema (como fizemos)
  • ✓Considere um secret manager para produção (HashiCorp Vault, AWS Secrets Manager)
5

🔑 Autenticação sem Browser

Servidores Linux não têm interface gráfica. A autenticação via browser OAuth não funciona em ambientes headless. Use API key via variável de ambiente como único método de autenticação.

Configuração completa de autenticação headless

# 1. Gere sua API key em:
#    console.anthropic.com → API Keys → Create Key
#    OU em openrouter.ai/keys

# 2. Configure no servidor:
echo 'export ANTHROPIC_AUTH_TOKEN="sk-ant-SUA-CHAVE"' >> ~/.bashrc
source ~/.bashrc

# Para OpenRouter (recomendado para modelos gratuitos):
echo 'export ANTHROPIC_BASE_URL="https://openrouter.ai/api"' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN="sk-or-v1-SUA-CHAVE"' >> ~/.bashrc
source ~/.bashrc

# 3. Testar autenticação:
claude -p "Responda: servidor configurado com sucesso"

🔍 Verificação de autenticação 

# Verificar variáveis ativas:
env | grep ANTHROPIC

# Teste completo:
claude -p "Qual é 1+1?" --no-interactive
# Deve retornar: 2

# Se falhar com erro de autenticação:
# 1. Verifique a chave: echo $ANTHROPIC_AUTH_TOKEN
# 2. Recarregue: source ~/.bashrc
# 3. Confirme que a chave não expirou no console
6

📟 Sessões Persistentes com tmux

O tmux (terminal multiplexer) mantém sessões ativas no servidor mesmo após você desconectar do SSH. É essencial para sessões longas do Claude Code em servidores.

Guia completo do tmux com Claude Code

# Instalar tmux (se não tiver)
sudo apt install -y tmux

# Criar nova sessão chamada "claude"
tmux new -s claude

# ====== Dentro do tmux ======

# Iniciar Claude Code
claude

# Para DESANEXAR (sair sem fechar):
# Pressione: Ctrl+B  depois  D
# O Claude Code continua rodando!

# ====== De volta ao terminal normal ======

# Listar sessões ativas:
tmux ls
# Saída: claude: 1 windows (created ...)

# Reanexar à sessão:
tmux attach -t claude
# OU forma curta:
tmux a -t claude

Comandos essenciais do tmux

Sessões

  • tmux new -s nome — criar sessão
  • tmux ls — listar sessões
  • tmux attach -t nome — reanexar
  • tmux kill-session -t nome — encerrar

Atalhos (Ctrl+B depois...)

  • D — desanexar da sessão
  • % — dividir painel verticalmente
  • " — dividir painel horizontalmente
  • Setas — navegar entre painéis

💡 Dica: Oracle Free Tier — VPS Gratuita para Sempre

A Oracle Cloud Free Tier oferece 2 VMs ARM gratuitas permanentemente. Para registrar, acesse cloud.oracle.com e selecione "Always Free Resources".

  • •Ampere A1: até 4 vCPUs ARM e 24GB RAM no total (gratuito!)
  • •Ubuntu 22.04 disponível
  • •Requer cartão de crédito para verificação (não cobra se ficar no free tier)

🎯 Resumo do Módulo 2.4

✓
VPS escolhida e acessível via SSH — com chaves SSH configuradas para segurança
✓
Node.js instalado via nvm — sem sudo, isolado no diretório do usuário
✓
Claude Code instalado e autenticado — via API key no .bashrc, sem necessidade de browser
✓
tmux configurado — sessões persistentes mesmo após desconexão SSH
✓
Segurança básica aplicada — usuário não-root, chaves SSH, API key protegida

Trilha Concluída! Próxima Trilha:

Trilha 3 — 🟣 Ollama Local — Configure modelos de IA rodando 100% no seu computador, sem custos de API

← Módulo 2.3: Mac Trilha 3: Ollama →