Exécuter Claude Code sur un VPS

Claude Code est un agent de codage basé sur le terminal. Il lit votre codebase, modifie des fichiers, exécute des commandes et construit des fonctionnalités à partir de descriptions en langage naturel. L'exécuter sur un VPS vous donne un agent de codage persistant, actif 24h/24 et accessible depuis n'importe quel appareil via SSH.

Ce guide vous accompagne d'un VPS Ubuntu vierge à une installation fonctionnelle de Claude Code avec persistance de session. Chaque étape inclut une commande de vérification pour confirmer le bon fonctionnement.

De quoi Claude Code a-t-il besoin sur un VPS ?

Claude Code envoie vos prompts aux serveurs d'Anthropic pour l'inférence. Votre VPS ne stocke que les fichiers du projet, les outils de développement et le processus Claude Code lui-même. Vous n'avez donc besoin ni d'un GPU ni d'un matériel haut de gamme.

Prérequis	Minimum	Recommandé
OS	Ubuntu 20.04 LTS	Ubuntu 24.04 LTS
RAM	4 Go	8 Go
Disque	20 Go SSD	40 Go NVMe
CPU	2 vCPUs	4 vCPUs
Réseau	Internet stable	Connexion faible latence
Dépendances	Aucune (installeur natif)	git, ripgrep (inclus)

L'installeur natif intègre ripgrep et ne nécessite aucune dépendance d'exécution comme Node.js. Un VPS de 4 Go gère Claude Code et un projet de taille moyenne. Si vous travaillez avec de gros monorepos ou exécutez des services supplémentaires, optez pour 8 Go.

Prérequis de compte : Claude Code nécessite un compte Claude Pro, Max, Teams, Enterprise ou Console. Le plan gratuit Claude.ai n'inclut pas l'accès à Claude Code.

Comment sécuriser un VPS avant d'installer Claude Code ?

Verrouillez votre serveur avant d'installer quoi que ce soit. Un VPS subit des attaques par force brute automatisées dans les minutes qui suivent sa mise en ligne. Ces étapes créent un utilisateur non-root, imposent l'authentification par clé SSH, configurent un pare-feu et activent les mises à jour de sécurité automatiques.

Si vous avez déjà un serveur renforcé, passez directement à Comment installer Claude Code sur un serveur Linux ?. Pour un guide plus détaillé de chaque étape de sécurité, consultez .

Créer un utilisateur non-root

Connectez-vous en SSH à votre serveur en tant que root, puis créez un utilisateur avec les privilèges sudo :

ssh root@YOUR_SERVER_IP

adduser claude
usermod -aG sudo claude

Copiez votre clé SSH vers le nouvel utilisateur pour vous connecter sans mot de passe :

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

Vérifiez que vous pouvez vous connecter avec le nouvel utilisateur depuis un second terminal avant de continuer. Ne fermez pas encore votre session root :

ssh claude@YOUR_SERVER_IP

Vous devriez obtenir un prompt shell en tant que claude@yourserver. Si cela fonctionne, poursuivez.

Désactiver l'authentification par mot de passe

Modifiez la configuration SSH pour bloquer les connexions par mot de passe :

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

Redémarrez SSH et vérifiez que les paramètres sont appliqués :

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

Sortie attendue (l'ordre peut varier) :

permitrootlogin no
passwordauthentication no

Configurer le pare-feu

UFW (Uncomplicated Firewall) bloque tout le trafic entrant sauf ce que vous autorisez. Sur certaines images VPS minimales, il faut d'abord l'installer avec sudo apt install -y ufw.

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

Vérifiez les règles :

sudo ufw status

Sortie attendue :

Status: active

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

Installer fail2ban

fail2ban bannit les adresses IP après des tentatives de connexion SSH répétées et échouées :

sudo apt update && sudo apt install -y fail2ban

Créez une configuration locale pour que vos paramètres survivent aux mises à jour du paquet :

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

Activez et vérifiez :

sudo systemctl enable --now fail2ban
sudo systemctl status fail2ban

Ouvrez l'œil : la sortie doit afficher active (running). Le flag enable --now lance fail2ban immédiatement et le fait survivre aux redémarrages.

sudo fail2ban-client status sshd

Cela montre que la jail est active avec 0 IP actuellement bannies (attendu sur une installation neuve).

Activer les mises à jour de sécurité automatiques

Unattended-upgrades corrige les vulnérabilités de sécurité sans intervention manuelle :

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

Sélectionnez « Yes » quand on vous le demande. Vérifiez que c'est actif :

sudo systemctl status unattended-upgrades

La sortie doit afficher active (running).

Comment installer Claude Code sur un serveur Linux ?

L'installeur natif est la méthode recommandée. Il ne nécessite aucune dépendance, se met à jour automatiquement en arrière-plan et fonctionne sur toute distribution Linux supportée. La méthode d'installation via npm est obsolète.

Lancez l'installeur en tant qu'utilisateur non-root (pas root) :

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

Il s'agit de l'installeur officiel d'Anthropic. Si vous préférez vérifier avant d'exécuter, consultez la documentation d'installation pour les sommes de contrôle SHA256 et les détails de signature de code.

L'installeur place le binaire dans ~/.local/bin/claude et l'ajoute à votre PATH. Ouvrez un nouveau shell ou sourcez votre profil pour prendre en compte le changement :

source ~/.bashrc

Vérifiez l'installation :

claude --version

Vous devriez voir un numéro de version comme 2.x.x. Lancez le diagnostic intégré pour vérifier votre configuration :

claude doctor

Cela vérifie la configuration système, la connectivité réseau et le statut d'authentification. À ce stade, l'authentification s'affichera comme incomplète. C'est normal.

Comment authentifier Claude Code sur un VPS headless ?

Claude Code ouvre normalement une fenêtre de navigateur pour la connexion OAuth. Sur un serveur headless sans interface graphique, il faut procéder autrement. Vous avez deux options selon votre type de compte.

Option A : clé API depuis Claude Console

Si vous avez un compte Claude Console (facturation par API), définissez la variable d'environnement ANTHROPIC_API_KEY. C'est la méthode la plus simple pour les serveurs headless.

Générez une clé API sur console.anthropic.com. Puis stockez-la de manière sécurisée sur votre 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

Ce que cela fait : crée un fichier dédié avec des permissions restreintes (seul votre utilisateur peut le lire) au lieu de mettre des secrets dans .bashrc où ils apparaissent dans l'historique du shell et sont lisibles par d'autres processus.

Chargez-le dans votre profil shell. Ajoutez cette ligne à ~/.bashrc :

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

Vérifiez que la clé est chargée :

echo $ANTHROPIC_API_KEY | head -c 15

Vous devriez voir sk-ant-api03-xx (les 15 premiers caractères de votre clé).

Option B : jeton OAuth depuis un abonnement Claude

Si vous utilisez un abonnement Claude Pro ou Max (pas Console), générez un jeton OAuth sur une machine avec un navigateur, puis transférez-le sur le VPS.

Sur votre machine locale (celle avec un navigateur) :

claude setup-token

Cela ouvre un navigateur pour l'authentification OAuth et produit un jeton longue durée commençant par sk-ant-oat01-. Le jeton est valide pendant un an.

Copiez le jeton, puis sur votre VPS, stockez-le de la même manière :

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

Vous devez aussi créer ~/.claude.json pour passer l'assistant de configuration :

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

Chargez-le dans votre profil shell :

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

Vérifier l'authentification

Testez que Claude Code peut atteindre les serveurs d'Anthropic :

claude -p "Say hello in exactly 5 words"

Le flag -p exécute un prompt unique sans entrer en mode interactif. Si vous voyez un message de cinq mots, l'authentification fonctionne. Si vous obtenez une erreur d'authentification, vérifiez que votre variable d'environnement est correctement définie avec env | grep -E 'ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN'.

Comment garder Claude Code actif après une déconnexion SSH ?

Utilisez tmux. Il crée des sessions terminal qui persistent sur le serveur indépendamment de votre connexion SSH. Fermez votre laptop, prenez un avion pour un autre pays, reconnectez-vous en SSH depuis votre téléphone. La session est toujours là, exactement où vous l'avez laissée.

Installer tmux

sudo apt install -y tmux

Vérification :

tmux -V

Configurer tmux pour Claude Code

Créez un .tmux.conf avec des paramètres optimisés pour les longues sessions de codage :

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

Démarrer une session Claude Code

Créez une session tmux nommée et lancez Claude Code dedans :

tmux new -s claude

Vous êtes maintenant dans une session tmux nommée « claude ». Démarrez Claude Code :

cd ~/your-project
claude

Claude Code tourne. Pour détacher la session (la laisser tourner en arrière-plan), appuyez sur :

Ctrl+B, puis D

Vous êtes de retour au prompt SSH normal. Claude Code continue de tourner dans tmux.

Aide-mémoire tmux

Action	Commande
Créer une session nommée	tmux new -s claude
Détacher la session	Ctrl+B, puis D
Lister les sessions	tmux ls
Se rattacher à une session	tmux attach -t claude
Supprimer une session	tmux kill-session -t claude
Défiler vers le haut	Ctrl+B, puis [, puis flèches
Quitter le mode défilement	q

Comment se reconnecter à une session Claude Code depuis un autre appareil ?

Connectez-vous en SSH à votre VPS depuis n'importe quel appareil et rattachez-vous :

ssh claude@YOUR_SERVER_IP
tmux attach -t claude

Votre session Claude Code est exactement où vous l'avez laissée. L'historique de conversation, le contexte des fichiers et les tâches en cours sont préservés. Cela fonctionne depuis un laptop, un téléphone (avec une app SSH comme Termius) ou un autre serveur.

Si la session a planté ou a été interrompue, tmux attach échouera. Démarrez-en une nouvelle :

tmux ls

Si aucune session n'est listée, créez-en une nouvelle avec tmux new -s claude.

Comment restreindre ce que Claude Code peut faire sur votre serveur ?

Claude Code dispose d'un système de permissions qui contrôle les outils qu'il peut utiliser. Par défaut, il demande confirmation avant d'exécuter des commandes bash ou de modifier des fichiers. Vous pouvez pré-approuver les commandes sûres et bloquer les dangereuses via .claude/settings.json dans le répertoire de votre projet.

N'utilisez jamais --dangerously-skip-permissions sur un vrai serveur. Cela contourne toutes les protections et permet à Claude Code d'exécuter n'importe quelle commande sans demander.

Configurer une liste blanche de permissions

Créez un fichier de configuration au niveau du projet :

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

Ce que cela fait : le tableau allow permet à Claude Code d'exécuter ces commandes sans demander à chaque fois. Le tableau deny bloque définitivement les commandes dangereuses. Les règles suivent une priorité deny-first : si une commande correspond à la fois à allow et deny, le deny l'emporte.

Vérifiez que le fichier a été créé avec les bonnes permissions :

ls -la .claude/settings.json

Le fichier doit être lisible par votre utilisateur. Comme ce fichier est commité dans git, il s'applique à tous ceux qui clonent le projet. Pour des surcharges personnelles, utilisez plutôt .claude/settings.local.json (automatiquement gitignored).

Comment surveiller les ressources de votre VPS ?

Claude Code sur un VPS de 4 Go utilise entre 200 et 400 Mo de RAM en fonctionnement normal. Les gros projets ou les tâches concurrentes multiples augmentent cette consommation. Configurer un espace de swap évite les arrêts par manque de mémoire.

Ajouter de l'espace de swap

Vérifiez si le swap existe déjà :

sudo swapon --show

Si la sortie est vide, créez un fichier swap de 2 Go :

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

Rendez-le persistant au redémarrage en l'ajoutant à /etc/fstab :

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

Vérification :

free -h

Vous devriez voir votre espace de swap listé. Ouvrez l'œil : cherchez la ligne Swap: affichant 2.0Gi au total.

Vérifier l'utilisation des ressources

Surveillez la mémoire et le CPU pendant que Claude Code tourne :

htop

Si htop n'est pas installé : sudo apt install -y htop. Surveillez la barre mémoire. Claude Code devrait se maintenir autour de 200-400 Mo. S'il atteint régulièrement 80 %+ de la RAM totale, envisagez de mettre à niveau votre VPS ou de fermer d'autres services.

Vérifiez l'utilisation du disque :

df -h /

Claude Code lui-même utilise peu de disque. Ce sont vos fichiers de projet et l'historique git qui consomment l'essentiel.

Combien coûte l'exécution de Claude Code sur un VPS ?

Claude Code fonctionne sur votre abonnement Claude existant sans frais supplémentaires. Votre coût mensuel total est le VPS plus le plan Claude.

Tier VPS	Coût mensuel	Plan Claude	Coût du plan	Total
2 vCPU, 4 Go RAM	~5-10 $	Pro	20 $/mois	25-30 $/mois
4 vCPU, 8 Go RAM	~10-20 $	Max	100 $/mois	110-120 $/mois
4 vCPU, 8 Go RAM	~10-20 $	Console (API)	Paiement au token	10-20 $ + usage

Le plan Pro inclut une utilisation limitée de Claude Code. Le plan Max offre des limites de débit plus élevées adaptées à une utilisation intensive. La facturation Console (API) est au token et convient aux équipes qui veulent un contrôle fin des coûts.

Pour un agent de codage persistant qui tourne en continu, le VPS 4 Go + plan Pro à environ 25 $/mois est le point d'entrée.

Quelque chose ne fonctionne pas ?

Claude Code ne s'authentifie pas

Vérifiez que votre variable d'environnement est définie :

env | grep -E 'ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN'

Si c'est vide, re-sourcez votre profil : source ~/.bashrc. Si la variable est définie mais que l'authentification échoue, vérifiez que la clé est valide. Les jetons OAuth expirent au bout d'un an. Les clés API peuvent être révoquées depuis la Console.

La session tmux a disparu

Les sessions tmux sont perdues quand le serveur redémarre. Après un redémarrage, lancez une nouvelle session :

tmux new -s claude

Pour vérifier si le serveur a redémarré récemment :

uptime

Claude Code est lent ou ne répond pas

Vérifiez la mémoire disponible :

free -h

Si la RAM est presque pleine et que le swap est fortement utilisé, Claude Code ralentira. Arrêtez les processus inutilisés ou mettez à niveau votre VPS. Vérifiez aussi la latence réseau vers les serveurs d'Anthropic :

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

Tout ce qui est sous 1 seconde est normal. Des valeurs plus élevées indiquent des problèmes réseau entre votre VPS et Anthropic.

Erreurs de permission refusée

Si Claude Code ne peut pas lire ou écrire des fichiers, vérifiez la propriété :

ls -la ~/your-project

Les fichiers doivent appartenir à votre utilisateur (claude:claude si vous avez suivi ce guide). Corrigez la propriété :

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

Consultez les logs pour plus de détails :

journalctl -u ssh -f

Cela affiche les logs SSH en temps réel. Utile pour déboguer les problèmes de connexion.

Copyright 2026 Virtua.Cloud. Tous droits réservés. Ce contenu est une création originale de l'équipe Virtua.Cloud. Toute reproduction, republication ou redistribution sans autorisation écrite est interdite.