Tutoriales de VPS
Desplegar Claude Code en un VPS (2026): instalación del entorno de desarrollo remoto, autenticación, aislamiento de permisos y tmux persistente
Despliega Claude Code en un VPS Ubuntu o Debian: configuración del servidor, instalación oficial, inicio de sesión sin escritorio, autenticación con ANTHROPIC_API_KEY, aislamiento de permisos entre usuario normal y proyecto, tmux persistente y recuperación tras cortes de SSH, además de comandos de diagnóstico para command not found, 403, fallos de autenticación y OOM, y una lista de verificación de seguridad para producción.

Desplegar Claude Code en un VPS (2026): instalación del entorno de desarrollo remoto, autenticación, aislamiento de permisos y tmux persistente
Ejecutar Claude Code en un VPS es adecuado para desarrollo remoto, diagnóstico de servidores y scripts de automatización que necesitan estar en línea a largo plazo. Tras iniciar sesión por SSH, ejecutas claude directamente dentro del repositorio Git, de modo que el código, las dependencias y el entorno de compilación permanecen en el servidor, mientras que tu equipo local solo se encarga de la conexión de terminal.
Este artículo usa Ubuntu 22.04/24.04 y Debian 12 como ejemplos para construir una configuración reutilizable: un usuario normal, la instalación oficial, autenticación sin escritorio, restricciones de permisos por proyecto y recuperación de sesiones tmux. Los requisitos oficiales de sistema de Claude Code son 4 GB o más de memoria, un procesador x64 o ARM64 y un entorno de red capaz de acceder a los servicios de Anthropic.
| Caso de uso | Configuración recomendada | Notas |
|---|---|---|
| Leer código, editar scripts pequeños | 2 núcleos / 4 GB / 40 GB SSD | Cumple el requisito mínimo oficial de memoria, adecuado para un solo repositorio |
| Compilar proyectos Node.js y Python | 4 núcleos / 8 GB / 80 GB NVMe | Deja margen para instalar dependencias, pruebas y compilación |
| Varios repositorios, Docker y bases de datos en paralelo | 4-8 núcleos / 16 GB / 120 GB NVMe | Evita que las tareas de compilación compitan por memoria e IO |
Aunque un VPS de 1 GB o 2 GB pueda iniciar el instalador, es fácil que sufra OOM durante npm install, la compilación de TypeScript o las compilaciones de Docker. Con presupuesto limitado, empieza con 4 GB y reserva al menos 10 GB de disco para el sistema.
Primero inicia sesión por SSH y actualiza el sistema:
ssh root@YOUR_SERVER_IP
apt update && apt full-upgrade -y
apt install -y ca-certificates curl git tmux ripgrep sudo
No dejes que las herramientas de IA se ejecuten como root a largo plazo. Crea una cuenta y un directorio de trabajo dedicados:
adduser coder
usermod -aG sudo coder
mkdir -p /srv/workspaces
chown -R coder:coder /srv/workspaces
su - coder
Después confirma que la red y la hora son correctas:
curl -I https://code.claude.com
timedatectl status
Si el propio SSH devuelve Permission denied, revisa primero las claves, los usuarios y los permisos de directorio con la lista de verificación para Permission denied de SSH en VPS y luego continúa con la instalación.
Ejecuta el comando oficial de instalación para Linux como el usuario coder:
curl -fsSL https://claude.ai/install.sh | bash
Recarga la configuración del shell y comprueba la versión:
export PATH="$HOME/.local/bin:$PATH"
claude --version
claude doctor
La instalación nativa oficial se actualiza automáticamente. Si el servidor necesita una versión fija o un canal estable, puedes instalar stable:
curl -fsSL https://claude.ai/install.sh | bash -s stable
No guardes la descarga de curl en el repositorio del proyecto ni uses sudo para instalar Claude Code en el directorio de usuario de root. Si aparece claude: command not found, revisa primero echo $PATH y ls -l ~/.local/bin/claude.
Inicia Claude Code en el directorio del proyecto:
mkdir -p /srv/workspaces/demo
cd /srv/workspaces/demo
claude
En la primera ejecución se muestra una URL de autorización. Cópiala en un navegador local para completar el inicio de sesión con una cuenta Claude Pro, Max, Team, Enterprise o Console y luego vuelve a la sesión SSH. Un VPS sin escritorio no necesita un navegador instalado; lo clave es mantener la conexión de terminal activa hasta que finalice la autorización.
Las tareas de automatización pueden usar ANTHROPIC_API_KEY. No escribas la clave directamente en el historial de comandos ni en Git:
read -s ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY
claude
unset ANTHROPIC_API_KEY
Para usarla en scripts fijos, crea un archivo de credenciales legible solo por el usuario actual:
install -m 600 /dev/null ~/.config/claude.env
printf 'ANTHROPIC_API_KEY=replace-me\n' > ~/.config/claude.env
set -a
. ~/.config/claude.env
set +a
Añade ~/.config/claude.env a la lista de exclusión de copias de seguridad y al .gitignore del proyecto. Al cambiar la clave, sobrescribe el archivo y ejecuta chmod 600 ~/.config/claude.env.
Coloca el repositorio donde coder pueda escribir y otros servicios no:
cd /srv/workspaces
git clone YOUR_REPOSITORY_URL demo
sudo chown -R coder:coder demo
cd demo
Puedes crear .claude/settings.json dentro del proyecto para exigir confirmación en comandos de alto riesgo y denegar la lectura del directorio de secretos:
{
"permissions": {
"allow": [
"Read(./**)",
"Edit(./**)",
"Bash(git status)",
"Bash(git diff)",
"Bash(npm test)"
],
"ask": [
"Bash(git push*)",
"Bash(docker *)",
"Bash(rm *)"
],
"deny": [
"Read(~/.ssh/**)",
"Read(~/.config/claude.env)",
"Bash(curl * | bash*)"
]
}
}
Las reglas deben ajustarse a los comandos reales del proyecto. No actives un modo totalmente automático de altos privilegios solo para ahorrarte pasos de confirmación; en un VPS de producción, conserva al menos la confirmación manual para commits de Git, borrados, Docker y descargas de red.
El desarrollo interactivo se lleva mejor en tmux:
tmux new -s claude-demo
cd /srv/workspaces/demo
claude
Pulsa Ctrl+b y luego d para desvincularte de la sesión; tras reconectarte al VPS, restáurala:
tmux ls
tmux attach -t claude-demo
Para continuar la conversación anterior, ejecuta claude --continue en el directorio del repositorio o usa claude --resume para seleccionar una sesión. tmux solo evita que el proceso de terminal se desconecte; no resuelve por ti la recuperación automática tras un reinicio del VPS ni es adecuado para aprobar cambios de alto riesgo sin supervisión.
Comprueba el DNS del servidor, la hora del sistema y el firewall de salida:
curl -v https://claude.ai/install.sh
getent hosts claude.ai
Si un proxy corporativo sustituye los certificados, importa la CA según la documentación oficial de configuración de red; no uses curl -k para eludir la verificación TLS.
command -v claude
ls -l ~/.local/bin/claude
echo $PATH
Añade export PATH="$HOME/.local/bin:$PATH" a ~/.bashrc y vuelve a iniciar sesión. Confirma que la instalación y la ejecución usan el mismo usuario de Linux.
Revisa el usuario actual y las variables de entorno:
whoami
env | grep '^ANTHROPIC_API_KEY=' | cut -c1-12
claude doctor
root y coder tienen directorios de configuración distintos, así que no puedes iniciar sesión como root y luego cambiar de usuario para ejecutarlo.
free -h
dmesg -T | grep -i -E 'oom|killed process'
Primero detén servicios no relacionados y reduce el número de compilaciones en paralelo; si sigue sufriendo OOM, amplía a 8 GB de memoria. El swap solo alivia los picos; no sustituye la memoria real.
- Claude Code se ejecuta con un usuario normal y el directorio de trabajo no contiene claves privadas SSH, copias de seguridad de bases de datos ni secretos de producción.
- El archivo de API Key tiene permisos
600, no se ha confirmado en Git ni se ha escrito en el historial del shell. - SSH solo permite inicio de sesión con clave, el firewall abre solo los puertos necesarios y los puertos de administración no están totalmente abiertos a internet.
- El
.claude/settings.jsondel proyecto mantiene la confirmación paragit push,rm, Docker y descargas externas. - Antes de cada cambio importante, crea una rama o un punto de commit en Git y, al terminar, revisa
git diffy los resultados de las pruebas. - Supervisa disco, memoria y tráfico de salida; los proyectos con Docker también deberían configurar healthcheck y límites de recursos, como se describe en la lista de verificación de configuración de producción de VPS Docker Compose.
Si ya usas un entorno de desarrollo remoto con Codex CLI en un VPS, el enfoque de despliegue de Claude Code es básicamente el mismo: un usuario normal, límites de autenticación claros y sesiones tmux son el núcleo de la estabilidad; las diferencias están principalmente en el sistema de cuentas, el nombre de la API Key y el formato del archivo de configuración de permisos.
Un VPS Linux desde 4 GB puede alojar el flujo de desarrollo remoto de Claude Code. Empieza con el instalador oficial y un usuario normal para completar la configuración mínima y luego añade reglas de permisos, sesiones tmux y monitorización según las necesidades del proyecto. Aislar la información de autenticación de los directorios de producción importa mucho más que perseguir simplemente una CPU más grande.