Ejecutar Claude Code en un VPS

Claude Code es un agente de codificación basado en terminal. Lee tu código fuente, edita archivos, ejecuta comandos y construye funcionalidades a partir de descripciones en lenguaje natural. Ejecutarlo en un VPS te da un agente de codificación persistente que funciona 24/7, accesible desde cualquier dispositivo por SSH.

Esta guía te lleva desde un VPS Ubuntu nuevo hasta una instalación funcional de Claude Code con persistencia de sesión. Cada paso incluye un comando de verificación para confirmar que funcionó.

¿Qué necesita Claude Code de un VPS?

Claude Code envía tus prompts a los servidores de Anthropic para la inferencia. Tu VPS solo almacena los archivos del proyecto, las herramientas de desarrollo y el proceso de Claude Code. Esto significa que no necesitas GPU ni hardware de gama alta.

Requisito	Mínimo	Recomendado
OS	Ubuntu 20.04 LTS	Ubuntu 24.04 LTS
RAM	4 GB	8 GB
Disco	20 GB SSD	40 GB NVMe
CPU	2 vCPUs	4 vCPUs
Red	Internet estable	Conexión de baja latencia
Dependencias	Ninguna (instalador nativo)	git, ripgrep (incluidos)

El instalador nativo incluye ripgrep y no requiere dependencias de ejecución como Node.js. Un VPS de 4 GB maneja Claude Code y un proyecto de tamaño medio. Si trabajas con monorepos grandes o ejecutas servicios adicionales, elige 8 GB.

Requisito de cuenta: Claude Code requiere una cuenta Claude Pro, Max, Teams, Enterprise o Console. El plan gratuito de Claude.ai no incluye acceso a Claude Code.

¿Cómo asegurar un VPS antes de instalar Claude Code?

Bloquea tu servidor antes de instalar nada. Un VPS recibe ataques de fuerza bruta automatizados minutos después de estar en línea. Estos pasos crean un usuario no root, imponen autenticación por clave SSH, configuran un firewall y activan actualizaciones de seguridad automáticas.

Si ya tienes un servidor reforzado, salta a ¿Cómo instalar Claude Code en un servidor Linux?. Para un recorrido más detallado de cada paso de seguridad, consulta .

Crear un usuario no root

Conéctate por SSH a tu servidor como root y luego crea un usuario con privilegios sudo:

ssh root@YOUR_SERVER_IP

adduser claude
usermod -aG sudo claude

Copia tu clave SSH al nuevo usuario para poder iniciar sesión sin contraseña:

mkdir -p /home/claude/.ssh
cp /root/.ssh/authorized_keys /home/claude/.ssh/authorized_keys
chown -R claude:claude /home/claude/.ssh
chmod 700 /home/claude/.ssh
chmod 600 /home/claude/.ssh/authorized_keys

Verifica que puedes iniciar sesión con el nuevo usuario desde un segundo terminal antes de continuar. No cierres tu sesión root todavía:

ssh claude@YOUR_SERVER_IP

Deberías obtener un prompt de shell como claude@yourserver. Si funciona, continúa.

Desactivar la autenticación por contraseña

Edita la configuración SSH para bloquear los inicios de sesión por contraseña:

sudo sed -i 's/^#\?PasswordAuthentication.*/PasswordAuthentication no/' /etc/ssh/sshd_config
sudo sed -i 's/^#\?PermitRootLogin.*/PermitRootLogin no/' /etc/ssh/sshd_config

Reinicia SSH y verifica que los ajustes se aplicaron:

sudo systemctl restart ssh
sudo sshd -T | grep -E 'passwordauthentication|permitrootlogin'

Salida esperada (el orden puede variar):

permitrootlogin no
passwordauthentication no

Configurar el firewall

UFW (Uncomplicated Firewall) bloquea todo el tráfico entrante excepto lo que permitas. En algunas imágenes VPS mínimas, puede que necesites instalarlo primero con sudo apt install -y ufw.

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw enable

Verifica las reglas:

sudo ufw status

Salida esperada:

Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
OpenSSH (v6)               ALLOW       Anywhere (v6)

Instalar fail2ban

fail2ban bloquea direcciones IP después de intentos fallidos repetidos de inicio de sesión SSH:

sudo apt update && sudo apt install -y fail2ban

Crea una configuración local para que tus ajustes sobrevivan a las actualizaciones del paquete:

sudo tee /etc/fail2ban/jail.local > /dev/null << 'EOF'
[sshd]
enabled = true
port = ssh
filter = sshd
maxretry = 5
bantime = 3600
findtime = 600
EOF

Activa y verifica:

sudo systemctl enable --now fail2ban
sudo systemctl status fail2ban

Fíjate bien: la salida debe mostrar active (running). El flag enable --now inicia fail2ban de inmediato y lo hace sobrevivir a reinicios.

sudo fail2ban-client status sshd

Esto muestra que la jail está activa con 0 IPs bloqueadas actualmente (esperado en una instalación nueva).

Activar las actualizaciones de seguridad automáticas

Unattended-upgrades corrige vulnerabilidades de seguridad sin intervención manual:

sudo apt install -y unattended-upgrades
sudo dpkg-reconfigure -plow unattended-upgrades

Selecciona "Yes" cuando se te solicite. Verifica que está activo:

sudo systemctl status unattended-upgrades

La salida debe mostrar active (running).

¿Cómo instalar Claude Code en un servidor Linux?

El instalador nativo es el método recomendado. No requiere dependencias, se actualiza automáticamente en segundo plano y funciona en cualquier distribución Linux compatible. El método de instalación por npm está obsoleto.

Ejecuta el instalador como tu usuario no root (no como root):

curl -fsSL https://claude.ai/install.sh | bash

Este es el instalador oficial de Anthropic. Si prefieres verificar antes de ejecutar, puedes consultar la documentación de instalación para sumas de verificación SHA256 y detalles de firma de código.

El instalador coloca el binario en ~/.local/bin/claude y lo añade a tu PATH. Abre un nuevo shell o recarga tu perfil para aplicar el cambio:

source ~/.bashrc

Verifica la instalación:

claude --version

Deberías ver un número de versión como 2.x.x. Ejecuta el diagnóstico integrado para verificar tu configuración:

claude doctor

Esto verifica la configuración del sistema, la conectividad de red y el estado de autenticación. En este punto, la autenticación aparecerá como incompleta. Eso es esperado.

¿Cómo autenticar Claude Code en un VPS headless?

Claude Code normalmente abre una ventana del navegador para el inicio de sesión OAuth. En un servidor headless sin interfaz gráfica, necesitas un enfoque diferente. Tienes dos opciones dependiendo de tu tipo de cuenta.

Opción A: clave API desde Claude Console

Si tienes una cuenta Claude Console (facturación basada en API), define la variable de entorno ANTHROPIC_API_KEY. Es el método más simple para servidores headless.

Genera una clave API en console.anthropic.com. Luego almacénala de forma segura en tu VPS:

sudo mkdir -p /etc/claude-code
sudo tee /etc/claude-code/env > /dev/null << 'EOF'
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
EOF
sudo chmod 600 /etc/claude-code/env
sudo chown claude:claude /etc/claude-code/env

Qué hace esto: crea un archivo dedicado con permisos restringidos (solo tu usuario puede leerlo) en lugar de poner secretos en .bashrc donde aparecen en el historial del shell y son legibles por otros procesos.

Cárgalo en tu perfil de shell. Añade esta línea a ~/.bashrc:

echo 'set -a; source /etc/claude-code/env; set +a' >> ~/.bashrc
source ~/.bashrc

Verifica que la clave está cargada:

echo $ANTHROPIC_API_KEY | head -c 15

Deberías ver sk-ant-api03-xx (los primeros 15 caracteres de tu clave).

Opción B: token OAuth desde una suscripción Claude

Si usas una suscripción Claude Pro o Max (no Console), genera un token OAuth en una máquina con navegador y luego transfiérelo al VPS.

En tu máquina local (la que tiene navegador):

claude setup-token

Esto abre un navegador para autenticación OAuth y genera un token de larga duración que empieza con sk-ant-oat01-. El token es válido durante un año.

Copia el token. Luego en tu VPS, almacénalo de la misma forma:

sudo tee /etc/claude-code/env > /dev/null << 'EOF'
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-your-token-here
EOF
sudo chmod 600 /etc/claude-code/env
sudo chown claude:claude /etc/claude-code/env

También necesitas crear ~/.claude.json para saltar el asistente de configuración:

cat > ~/.claude.json << 'EOF'
{
  "hasCompletedOnboarding": true
}
EOF
chmod 600 ~/.claude.json

Cárgalo en tu perfil de shell:

echo 'set -a; source /etc/claude-code/env; set +a' >> ~/.bashrc
source ~/.bashrc

Verificar la autenticación

Prueba que Claude Code puede comunicarse con los servidores de Anthropic:

claude -p "Say hello in exactly 5 words"

El flag -p ejecuta un prompt único sin entrar en modo interactivo. Si ves un saludo de cinco palabras, la autenticación funciona. Si obtienes un error de autenticación, verifica que tu variable de entorno está correctamente definida con env | grep -E 'ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN'.

¿Cómo mantener Claude Code ejecutándose tras desconectar SSH?

Usa tmux. Crea sesiones de terminal que persisten en el servidor independientemente de tu conexión SSH. Cierra tu laptop, vuela a otro país, reconéctate por SSH desde tu teléfono. La sesión sigue ahí, exactamente donde la dejaste.

Instalar tmux

sudo apt install -y tmux

Verificación:

tmux -V

Configurar tmux para Claude Code

Crea un .tmux.conf con ajustes optimizados para sesiones largas de codificación:

cat > ~/.tmux.conf << 'EOF'
# Increase scrollback buffer (default is 2000 lines)
set -g history-limit 50000

# Enable mouse support for scrolling and pane selection
set -g mouse on

# Start window numbering at 1
set -g base-index 1

# Reduce escape time for faster key response
set -sg escape-time 10

# Status bar with session name and time
set -g status-right '%H:%M %d-%b'

# Keep sessions alive if the shell exits unexpectedly
set -g remain-on-exit on
EOF

Iniciar una sesión de Claude Code

Crea una sesión tmux con nombre y lanza Claude Code dentro:

tmux new -s claude

Ahora estás dentro de una sesión tmux llamada "claude". Inicia Claude Code:

cd ~/your-project
claude

Claude Code está ejecutándose. Para separarte de la sesión (dejarla ejecutándose en segundo plano), presiona:

Ctrl+B, luego D

Estás de vuelta en tu prompt SSH normal. Claude Code sigue ejecutándose dentro de tmux.

Referencia rápida de tmux

Acción	Comando
Crear sesión con nombre	tmux new -s claude
Separarse de la sesión	Ctrl+B, luego D
Listar sesiones	tmux ls
Reconectarse a una sesión	tmux attach -t claude
Eliminar sesión	tmux kill-session -t claude
Desplazarse hacia arriba	Ctrl+B, luego [, luego flechas
Salir del modo desplazamiento	q

¿Cómo reconectarse a una sesión de Claude Code desde otro dispositivo?

Conéctate por SSH a tu VPS desde cualquier dispositivo y reconéctate:

ssh claude@YOUR_SERVER_IP
tmux attach -t claude

Tu sesión de Claude Code está exactamente donde la dejaste. El historial de conversación, el contexto de archivos y las tareas en ejecución se conservan. Funciona desde un laptop, teléfono (usando una app SSH como Termius) u otro servidor.

Si la sesión se cayó o fue terminada, tmux attach fallará. Inicia una nueva:

tmux ls

Si no hay sesiones listadas, crea una nueva con tmux new -s claude.

¿Cómo restringir lo que Claude Code puede hacer en tu servidor?

Claude Code tiene un sistema de permisos que controla qué herramientas puede usar. Por defecto, pide confirmación antes de ejecutar comandos bash o editar archivos. Puedes pre-aprobar comandos seguros y bloquear los peligrosos usando .claude/settings.json en el directorio de tu proyecto.

Nunca uses --dangerously-skip-permissions en un servidor real. Esto omite todas las protecciones y permite a Claude Code ejecutar cualquier comando sin preguntar.

Configurar una lista blanca de permisos

Crea un archivo de configuración a nivel de proyecto:

cd ~/your-project
mkdir -p .claude
cat > .claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(npm test *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(ls *)",
      "Bash(cat *)",
      "Read",
      "Bash(grep *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(chmod 777 *)",
      "Bash(curl * | bash)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}
EOF

Qué hace esto: el array allow permite a Claude Code ejecutar esos comandos sin preguntar cada vez. El array deny bloquea los comandos peligrosos por completo. Las reglas siguen una precedencia deny-first: si un comando coincide con allow y deny, el deny gana.

Verifica que el archivo fue creado con los permisos correctos:

ls -la .claude/settings.json

El archivo debe ser legible por tu usuario. Como este archivo se commitea en git, se aplica a todos los que clonen el proyecto. Para sobrescrituras personales, usa .claude/settings.local.json (automáticamente ignorado por git).

¿Cómo monitorear los recursos de tu VPS?

Claude Code en un VPS de 4 GB usa entre 200-400 MB de RAM durante operación normal. Proyectos grandes o múltiples tareas concurrentes aumentan este valor. Configurar espacio de swap previene que el sistema mate procesos por falta de memoria.

Añadir espacio de swap

Verifica si ya existe swap:

sudo swapon --show

Si la salida está vacía, crea un archivo swap de 2 GB:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Hazlo persistente tras reinicios añadiéndolo a /etc/fstab:

echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Verificación:

free -h

Deberías ver tu espacio de swap listado. Fíjate bien: busca la fila Swap: mostrando 2.0Gi total.

Verificar el uso de recursos

Monitorea memoria y CPU mientras Claude Code está ejecutándose:

htop

Si htop no está instalado: sudo apt install -y htop. Observa la barra de memoria. Claude Code debería mantenerse alrededor de 200-400 MB. Si alcanza consistentemente el 80 %+ de la RAM total, considera actualizar tu VPS o cerrar otros servicios.

Verifica el uso de disco:

df -h /

Claude Code en sí usa mínimo disco. Tus archivos de proyecto y el historial de git son los principales consumidores.

¿Cuánto cuesta ejecutar Claude Code en un VPS?

Claude Code funciona con tu suscripción Claude existente sin coste adicional. Tu coste mensual total es el VPS más el plan Claude.

Tier VPS	Coste mensual	Plan Claude	Coste del plan	Total
2 vCPU, 4 GB RAM	~5-10 $	Pro	20 $/mes	25-30 $/mes
4 vCPU, 8 GB RAM	~10-20 $	Max	100 $/mes	110-120 $/mes
4 vCPU, 8 GB RAM	~10-20 $	Console (API)	Pago por token	10-20 $ + uso

El plan Pro incluye uso limitado de Claude Code. El plan Max tiene límites de tasa más altos para uso intensivo. La facturación Console (API) cobra por token y es adecuada para equipos que necesitan control detallado de costes.

Para un agente de codificación persistente que funciona las 24 horas, el VPS de 4 GB + plan Pro a unos 25 $/mes es el punto de entrada.

¿Algo salió mal?

Claude Code no se autentica

Verifica que tu variable de entorno está definida:

env | grep -E 'ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN'

Si está vacía, recarga tu perfil: source ~/.bashrc. Si la variable está definida pero la autenticación falla, verifica que la clave sea válida. Los tokens OAuth expiran después de un año. Las claves API pueden revocarse desde la Console.

La sesión tmux desapareció

Las sesiones tmux se pierden cuando el servidor se reinicia. Después de un reinicio, inicia una nueva sesión:

tmux new -s claude

Para verificar si el servidor se reinició recientemente:

uptime

Claude Code está lento o no responde

Verifica la memoria disponible:

free -h

Si la RAM está casi llena y el swap se usa mucho, Claude Code se ralentizará. Mata procesos no utilizados o actualiza tu VPS. También verifica la latencia de red hacia los servidores de Anthropic:

curl -o /dev/null -s -w '%{time_total}\n' https://api.anthropic.com

Cualquier valor bajo 1 segundo es normal. Valores más altos sugieren problemas de red entre tu VPS y Anthropic.

Errores de permiso denegado

Si Claude Code no puede leer o escribir archivos, verifica la propiedad:

ls -la ~/your-project

Los archivos deben pertenecer a tu usuario (claude:claude si seguiste esta guía). Corrige la propiedad:

sudo chown -R claude:claude ~/your-project

Consulta los logs para más detalle:

journalctl -u ssh -f

Esto muestra los logs de SSH en tiempo real. Útil para depurar problemas de conexión.

Copyright 2026 Virtua.Cloud. Todos los derechos reservados. Este contenido es una obra original del equipo de Virtua.Cloud. La reproducción, republicación o redistribución sin permiso escrito está prohibida.