Claude Code auf einem VPS

Problem: Claude Code fühlt sich auf dem Laptop natürlich an, aber ein Remote-Server klingt nach einem anderen Sport. Vielleicht willst du es 24/7 für lange Jobs laufen lassen. Vielleicht brauchst du es von mehreren Maschinen aus erreichbar, ohne Umgebungen mitzuschleppen. Oder du willst die schwere KI-Arbeit einfach vom Laptop-Akku fernhalten.

Claude Code auf einem VPS zu betreiben ist simpel, sobald die einzelnen Teile klar sind: SSH, Node.js, Authentifizierung und Docker zur Isolation (optional). Diese Anleitung geht den kompletten Setup durch mit echten Befehlen, die du direkt in eine frische Ubuntu-Box einfügen kannst.

VPS auswählen und was du brauchst

Claude Code ist hungriger als eine typische Node-App. Das Modell selbst läuft auf Anthropics Servern, aber der lokale Prozess kümmert sich trotzdem um Context Management, Dateioperationen und Tool-Ausführung.

Mindestanforderungen für den VPS:

• 2 vCPUs (4 empfohlen für Multi-Agent-Workloads)
• 4 GB RAM (8 GB empfohlen)
• 40 GB SSD-Speicher
• Ubuntu 22.04 oder 24.04 LTS

Anbieter, die gut funktionieren: Jeder große VPS-Anbieter läuft damit problemlos. AWS Lightsail, DigitalOcean, Hetzner und Linode verkaufen alle $10-20/Monat-Pakete, die diese Specs übertreffen. Hetzner gewinnt beim Preis-Leistungs-Verhältnis für europäische Entwickler. Lightsail ist am einfachsten, wenn du sowieso schon in der AWS-Welt lebst.

Was du vor dem Start brauchst:

• Ein Anthropic API-Key (von console.anthropic.com) oder ein Pro/Max-Abo
• SSH-Zugang zum Server
• Ein Domainname (optional, für Remote-Control-Zugang)

SSH-Setup und sicherer Zugang

Fang mit einem frischen Ubuntu-Server an. Die meisten Anbieter lassen dich als root mit einem Passwort rein. Erster Job: dicht machen.

# Mit deinem neuen Server verbinden
ssh root@your-server-ip
 
# Nicht-Root-Benutzer anlegen
adduser deploy
usermod -aG sudo deploy
 
# SSH-Key-Authentifizierung einrichten
mkdir -p /home/deploy/.ssh
# Deinen Public Key kopieren (das hier von deiner LOKALEN Maschine aus ausführen):
# ssh-copy-id deploy@your-server-ip
 
# Passwort-Authentifizierung deaktivieren
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

Eine einfache Firewall aufsetzen, bevor du irgendetwas installierst:

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

Ab jetzt immer als Nicht-Root-Benutzer verbinden: ssh deploy@your-server-ip.

Claude Code auf einem headless Server installieren

Claude Code braucht Node.js 18+. Nutze das NodeSource-Repo für das aktuelle LTS:

# Node.js 22 LTS installieren
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
 
# Installation prüfen
node --version  # Sollte v22.x zeigen
npm --version
 
# Claude Code global installieren
npm install -g @anthropic-ai/claude-code
 
# Claude Code-Installation prüfen
claude --version

Authentifizierung: Auf einem headless Server ohne Browser authentifizierst du dich mit einem API-Key.

# Deinen Anthropic API-Key setzen
export ANTHROPIC_API_KEY="sk-ant-..."
 
# Oder für persistente Sessions zum Shell-Profil hinzufügen
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
source ~/.bashrc

Hast du ein Pro- oder Max-Abo und willst stattdessen OAuth? Führe claude einmal aus, kopiere die Auth-URL, die es ausgibt, öffne sie in einem Browser auf einem beliebigen Gerät und füge den Code zurück ins Terminal ein.

Claude Code im nicht-interaktiven Modus betreiben

Auf einem Server ist der nützliche Modus headless, nicht interaktiver Chat. Hier wird Automatisierung real.

Einzelner Befehl:

# Einen einzelnen Task ausführen und beenden
claude -p "Review the codebase in /opt/apps/myproject and list any security issues"
 
# Input für die Verarbeitung pipen
cat error-log.txt | claude -p "Analyze these errors and suggest fixes"

Das -p-Flag (Print-Modus) lässt Claude Code nicht-interaktiv laufen. Es liest den Prompt, druckt das Ergebnis, beendet sich. Keine Chat-UI. Kein Warten auf Input.

Mit SSH kombinieren für Remote-Management: Hier fängt ein VPS-gehostetes Claude Code an, seinen Wert zu beweisen. Von deiner lokalen Maschine aus:

# Claude Code auf deinem Server von deinem Laptop aus ausführen
ssh deploy@your-server "cd /opt/apps/myproject && claude -p 'Run the test suite and fix any failures'"

Du kannst auch Remote Control nutzen, um in eine laufende interaktive Session von deinem Handy oder einem anderen Gerät einzuspringen, was bei der Überwachung langer Agent-Runs hilft.

Docker-Deployment-Workflow

Docker fügt Isolation und Reproduzierbarkeit hinzu. Etwas kaputt? Du reißt den Container runter und spinnst einen neuen. Kein Aufräumen eines verseuchten Servers.

Erstelle eine docker-compose.yml für deinen Claude Code-Workspace:

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:

Den Workspace starten und nutzen:

# Container starten
docker compose up -d
 
# Claude Code im Container ausführen
docker exec -it claude-code claude -p "List all files in the workspace"
 
# Eine interaktive Session öffnen
docker exec -it claude-code claude
 
# Container-Logs ansehen
docker logs claude-code

Die Zeile tail -f /dev/null hält den Container am Leben, damit du beliebig oft in ihn hineinexecen kannst. Das claude-cache-Volume bewahrt Claudes Auth- und Session-Daten zwischen Container-Neustarts.

Für projektspezifische Container nutze separate Compose-Dateien pro Projekt. Jedes bekommt seine eigene isolierte Umgebung mit nur den benötigten Dateien.

Monitoring und Log-Management

Langlaufende Claude Code-Sessions auf einem VPS brauchen Augen. Ein Prozess, der still um 3 Uhr nachts abstürzt, ist nichts, was du haben willst.

Nutze tmux oder screen für Sessions, die SSH-Trennungen überleben:

# Eine neue tmux-Session starten
tmux new -s claude-session
 
# Claude Code innerhalb von tmux ausführen
cd /opt/apps/myproject
claude
 
# Loslösen: Ctrl+B, dann D
# Später wieder anhängen:
tmux attach -t claude-session

Systemd-Service für immer laufende Claude Code-Worker:

# /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
 
# Status prüfen
sudo systemctl status claude-worker
 
# Logs ansehen
journalctl -u claude-worker -f

Häufige Fehler und echte Lösungen

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

Du hast Node.js als root installiert und jetzt braucht npm Schreibzugriff für globale Installationen. Fix:

sudo chown -R $(whoami) /usr/lib/node_modules
# Oder besser: einen Node-Versionsmanager wie nvm verwenden

"Error: Unable to open browser for authentication"

Normal auf einem headless Server. Nutze die API-Key-Methode oben, oder füge die Auth-URL in einem Browser auf einem anderen Gerät ein.

Claude Code-Prozess durch OOM (Out of Memory) gekillt

Dein VPS hat zu wenig RAM. Multi-Agent-Sessions, die viele Sub-Agents spawnen, verbrauchen Speicher pro Agent. Lösungen:

# Aktuellen Speicherverbrauch prüfen
free -h
 
# Swap-Space hinzufügen, falls du keinen hast
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

SSH-Verbindung bricht während langer Claude Code-Sessions ab

Setze SSH Keep-Alive auf deiner lokalen Maschine:

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

Oder im tmux laufen lassen (oben), damit die Session weiterläuft, auch wenn SSH abbricht.

Sicherheitsüberlegungen

Einen KI-Coding-Agent auf einem Server zu betreiben, der echte Credentials hält, erfordert extra Sorgfalt.

Niemals API-Keys committen. Umgebungsvariablen oder einen Secrets Manager verwenden:

# Eine .env-Datei verwenden, die in .gitignore steht
echo "ANTHROPIC_API_KEY=sk-ant-..." > /opt/apps/myproject/.env
 
# In der Shell laden
set -a; source /opt/apps/myproject/.env; set +a

Claude Codes Dateizugriff einschränken bei automatisierten Tasks. Das --sandbox-Flag begrenzt Dateisystem- und Netzwerkzugriff:

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

Fail2ban einrichten, um SSH-Brute-Force-Versuche zu blockieren:

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

Den Server gepatcht halten:

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

Was kommt als nächstes

Ein VPS-gehostetes Claude Code öffnet Workflows, die lokale Maschinen nicht können: 24/7-Verfügbarkeit, geplante Tasks, die laufen während du schläfst, und Multi-Agent-Sessions, die deinen Laptop-Akku nicht leeren. Kombiniere es mit Git-Worktrees für isolierte Branch-Arbeit, oder nutze Remote Control, um Sessions von deinem Handy aus zu steuern.

Fang klein an. Claude Code auf einem einfachen VPS über SSH zum Laufen bringen. Docker hinzufügen, wenn du Isolation brauchst. Systemd-Services hinzufügen, wenn du Automatisierung brauchst. Von da aus skalieren.