Claude Code sur un VPS

Le problème : Claude Code se sent naturel sur ton laptop, mais un serveur distant ressemble à un autre sport. Peut-être que tu veux le garder actif 24h/24 pour des jobs longs. Peut-être que tu as besoin d'y accéder depuis plusieurs machines sans trimballer des environnements. Ou tu veux juste décharger le travail lourd d'IA de ta batterie.

Faire tourner Claude Code sur un VPS, c'est simple une fois que les pièces du puzzle sont claires : SSH, Node.js, l'authentification, et Docker pour l'isolation (optionnel). Ce guide parcourt toute la configuration avec de vraies commandes que tu peux coller dans un Ubuntu vierge.

Choisir un VPS et ce dont tu as besoin

Claude Code est plus gourmand qu'une app Node classique. Le modèle tourne sur les serveurs d'Anthropic, mais le processus local gère quand même la gestion du contexte, les opérations sur fichiers, et l'exécution des outils.

Specs minimum pour le VPS :

• 2 vCPUs (4 recommandés pour les workloads multi-agents)
• 4 Go de RAM (8 Go recommandés)
• 40 Go de stockage SSD
• Ubuntu 22.04 ou 24.04 LTS

Providers qui fonctionnent bien : Tous les gros hébergeurs VPS gèrent ça sans drama. AWS Lightsail, DigitalOcean, Hetzner, et Linode proposent tous des plans à 10-20€/mois qui dépassent ces specs. Hetzner gagne sur le rapport qualité-prix pour les devs européens. Lightsail est le plus facile si tu vis déjà dans l'écosystème AWS.

Ce qu'il faut avoir avant de commencer :

• Une clé API Anthropic (depuis console.anthropic.com) ou un abonnement Pro/Max
• Un accès SSH au serveur
• Un nom de domaine (optionnel, pour l'accès Remote Control)

Configuration SSH et accès sécurisé

Commence avec un serveur Ubuntu vierge. La plupart des providers te connectent en tant que root avec un mot de passe. La première priorité, c'est de sécuriser tout ça.

# Connexion à ton nouveau serveur
ssh root@your-server-ip
 
# Créer un utilisateur non-root
adduser deploy
usermod -aG sudo deploy
 
# Configurer l'authentification par clé SSH
mkdir -p /home/deploy/.ssh
# Copie ta clé publique (lance ça depuis ta machine LOCALE à la place) :
# ssh-copy-id deploy@your-server-ip
 
# Désactiver l'authentification par mot de passe
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

Monte un pare-feu basique avant d'installer quoi que ce soit d'autre :

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

À partir de là, connecte-toi toujours en tant qu'utilisateur non-root : ssh deploy@your-server-ip.

Installer Claude Code sur un serveur headless

Claude Code a besoin de Node.js 18+. Utilise le repo NodeSource pour le LTS actuel :

# Installer Node.js 22 LTS
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
 
# Vérifier l'installation
node --version  # Doit afficher v22.x
npm --version
 
# Installer Claude Code globalement
npm install -g @anthropic-ai/claude-code
 
# Vérifier que Claude Code est installé
claude --version

Authentification : Sur un serveur headless sans navigateur, tu t'authentifies avec une clé API.

# Définir ta clé API Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
 
# Ou pour des sessions persistantes, ajoute-la à ton profil shell
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
source ~/.bashrc

Tu as un abonnement Pro ou Max et tu veux OAuth à la place ? Lance claude une fois, copie l'URL d'authentification qu'il affiche, ouvre-la dans un navigateur sur n'importe quel appareil, et colle le code dans le terminal.

Lancer Claude Code en mode non-interactif

Sur un serveur, le mode utile c'est headless, pas le chat interactif. C'est là que l'automatisation devient réelle.

Exécution d'une seule commande :

# Lancer une tâche unique et quitter
claude -p "Review the codebase in /opt/apps/myproject and list any security issues"
 
# Passer une entrée en pipe pour traitement
cat error-log.txt | claude -p "Analyze these errors and suggest fixes"

Le flag -p (mode print) lance Claude Code de façon non-interactive. Il lit le prompt, affiche le résultat, et quitte. Pas d'interface de chat. Pas d'attente d'entrée.

Combiné avec SSH pour la gestion à distance : C'est là qu'un Claude Code hébergé sur VPS commence à valoir son poids. Depuis ta machine locale :

# Lancer Claude Code sur ton serveur depuis ton laptop
ssh deploy@your-server "cd /opt/apps/myproject && claude -p 'Run the test suite and fix any failures'"

Tu peux aussi utiliser Remote Control pour rejoindre une session interactive active depuis ton téléphone ou un autre appareil, ce qui aide pour surveiller les longues exécutions d'agents.

Workflow de déploiement Docker

Docker ajoute isolation et reproductibilité. Quelque chose casse, tu détruis le conteneur et tu en lances un nouveau. Pas de nettoyage d'un serveur pollué.

Crée un docker-compose.yml pour ton espace de travail 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:

Démarre l'espace de travail et utilise-le :

# Démarrer le conteneur
docker compose up -d
 
# Exécuter Claude Code dans le conteneur
docker exec -it claude-code claude -p "List all files in the workspace"
 
# Ouvrir une session interactive
docker exec -it claude-code claude
 
# Voir les logs du conteneur
docker logs claude-code

La ligne tail -f /dev/null garde le conteneur vivant pour que tu puisses t'y connecter autant de fois que tu veux. Le volume claude-cache conserve les données d'auth et de session de Claude entre les redémarrages du conteneur.

Pour des conteneurs spécifiques par projet, utilise des fichiers compose séparés par projet. Chacun obtient son environnement isolé avec seulement les fichiers dont il a besoin montés.

Monitoring et gestion des logs

Les sessions Claude Code longues sur un VPS ont besoin d'être surveillées. Un processus qui plante silencieusement à 3h du mat, c'est pas ce que tu veux.

Utilise tmux ou screen pour des sessions qui survivent aux déconnexions SSH :

# Démarrer une nouvelle session tmux
tmux new -s claude-session
 
# Lancer Claude Code dans tmux
cd /opt/apps/myproject
claude
 
# Détacher : Ctrl+B, puis D
# Se rattacher plus tard :
tmux attach -t claude-session

Service systemd pour des workers Claude Code toujours actifs :

# /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
 
# Vérifier le statut
sudo systemctl status claude-worker
 
# Voir les logs
journalctl -u claude-worker -f

Erreurs courantes et vraies solutions

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

Tu as installé Node.js en tant que root et maintenant npm veut des droits d'écriture pour les installations globales. Solution :

sudo chown -R $(whoami) /usr/lib/node_modules
# Ou mieux : utilise un gestionnaire de version de node comme nvm

"Error: Unable to open browser for authentication"

Normal sur un serveur headless. Utilise la méthode par clé API ci-dessus, ou colle l'URL d'auth dans un navigateur sur un autre appareil.

Processus Claude Code tué par OOM (Out of Memory)

Ton VPS manque de RAM. Les sessions multi-agents qui lancent beaucoup de sous-agents consomment de la mémoire par agent. Solutions :

# Vérifier l'utilisation mémoire actuelle
free -h
 
# Ajouter de l'espace swap si tu n'en as pas
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

La connexion SSH se coupe pendant les longues sessions Claude Code

Configure SSH keep-alive sur ta machine locale :

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

Ou lance dans tmux (voir ci-dessus) pour que la session continue même si SSH se reconnecte.

Considérations de sécurité

Faire tourner un agent de codage IA sur un serveur qui contient de vraies credentials demande une attention particulière.

Ne commit jamais les clés API. Utilise des variables d'environnement ou un gestionnaire de secrets :

# Utilise un fichier .env ignoré par git
echo "ANTHROPIC_API_KEY=sk-ant-..." > /opt/apps/myproject/.env
 
# Charge dans ton shell
set -a; source /opt/apps/myproject/.env; set +a

Restreins l'accès aux fichiers de Claude Code sur les tâches automatisées. Le flag --sandbox limite l'accès au système de fichiers et au réseau :

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

Configure Fail2ban pour bloquer les tentatives de brute-force SSH :

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

Garde le serveur à jour :

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

La suite

Un Claude Code hébergé sur VPS ouvre des workflows impossibles sur une machine locale : uptime 24h/24, tâches planifiées qui tournent pendant que tu dors, et sessions multi-agents qui ne drainent pas ta batterie. Associe-le à des git worktrees pour un travail de branche isolé, ou utilise Remote Control pour piloter les sessions depuis ton téléphone.

Commence petit. Fais tourner Claude Code sur un VPS basique via SSH. Ajoute Docker quand tu as besoin d'isolation. Ajoute des services systemd quand tu as besoin d'automatisation. Développe à partir de là.