So planen Sie KI-Agenten für nächtliche Läufe auf einem VPS

Um 2 Uhr nachts startet ein geplanter Job auf einem VPS, der nie eingeschlafen ist. Ein Headless-Lauf von claude -p arbeitet eine eingereihte Aufgabe in einem geklonten Repository ab, ohne jemanden etwas zu fragen, und beendet sich dann. Wenn Sie morgens nachsehen, wartet ein Commit, ein Bericht oder ein Log, das genau zeigt, wo der Lauf gestoppt hat und warum. Niemand hat zugesehen.

Das ist etwas anderes, als ein Terminal die ganze Nacht offen zu lassen und zu hoffen, dass die SSH-Verbindung hält. Ein häufiger Schwachpunkt bei einem nächtlichen Agentenlauf ist der Host selbst: Ein Laptop geht in den Ruhezustand, der Deckel schließt sich, das Netzwerk bricht weg, oder ein Betriebssystem-Update startet die Maschine mitten in der Aufgabe neu. Authentifizierungsfehler, API-Fehler und blockierte Berechtigungsanfragen können den Job weiterhin beenden, aber ein durchgehend laufender Host beseitigt die einfachste Fehlerquelle.

Dieser Leitfaden behandelt den eigentlichen Mechanismus: die Headless-Flags, die jede große Coding-Agent-CLI mitbringt, die zwei Wege, einen Lauf nach Zeitplan auszulösen, und welcher davon der richtige ist, was der Host darunter braucht, und die Leitplanken, die verhindern, dass ein unbeaufsichtigter Lauf mehr kostet oder kaputt macht, als Sie später erklären möchten.

Die Kurzfassung

• Jede große Coding-Agent-CLI bringt einen dokumentierten nicht-interaktiven Modus mit, der einen Prompt bis zum Ende ausführt und sich dann beendet. Claude Code hat claude -p, Codex CLI hat codex exec, und Gemini CLI hat gemini -p. Das ist kein Workaround, sondern ein offizielles Feature.
• Claude Code hat außerdem eine eigene Planung: Routines, geplante Desktop-Aufgaben und /loop. Für manche Leser reicht das wirklich aus, und es gibt weniger zu warten als bei einem VPS.
• Cron reicht für einen nächtlichen Job völlig aus. Ein systemd-Timer ist auf einer Maschine, die neu starten könnte, die bessere Voreinstellung, weil Persistent=true einen Lauf nachholt, den cron stillschweigend übersprungen hätte.
• Die CLI selbst ist leichtgewichtig, weil die Inferenz auf der API des Anbieters läuft. Dimensionieren Sie den VPS für die Befehle, die er ausführen wird (Tests, Builds, Container, parallele Jobs), nicht für das Modell.
• Erst die Leitplanken (eingegrenzte Tools, ein Turn-Limit, Verzweigung über den Exit-Code) machen es sicher, einen Zeitplan sich selbst zu überlassen. Der Zeitplan allein ist nicht der Sicherheitsmechanismus.

Was Sie brauchen

Halten Sie diese fünf Dinge bereit, bevor Sie eine einzige crontab-Zeile oder Unit-Datei schreiben:

• Ein VPS, auf den Sie per SSH zugreifen können, mit einer systemd-basierten Linux-Distribution.
• Die Agent-CLI auf diesem VPS installiert: Claude Code, Codex CLI oder Gemini CLI.
• Ein nicht-interaktiver Zugang für die gewählte CLI. Der Bare-Modus von Claude Code liest keinen Konto-Login, er benötigt daher ANTHROPIC_API_KEY in der Umgebung oder einen apiKeyHelper in seinen Einstellungen. Ein normaler Lauf im Print-Modus, Codex und Gemini können auch die dokumentierten Konto-Zugangsdaten verwenden.
• Ein Repository oder Aufgabenverzeichnis, auf dem der Agent arbeitet.
• Shell-Zugang mit der Berechtigung, eine crontab zu bearbeiten oder eine systemd-Unit-Datei zu schreiben.

Einen Agenten ohne angehängte Sitzung ausführen

Jede große Coding-Agent-CLI bringt einen nicht-interaktiven Modus mit, der genau dafür gebaut ist. Claude Code nimmt -p, auch geschrieben als --print. Codex CLI nimmt codex exec. Gemini CLI nimmt -p, auch geschrieben als --prompt. Jeder nimmt einen Prompt entgegen, führt ihn zu Ende und beendet sich. Keine Chat-Schleife, kein Terminal, das offen bleiben muss, nichts, woran man sich wieder anhängen müsste.

Kann Claude Code ohne aktive Sitzung laufen? Ja. Mit -p läuft der Prompt im nicht-interaktiven Modus: Claude Code führt ihn zu Ende, gibt das Ergebnis aus und beendet sich. Es gibt keine Chat-Schleife und nichts am Leben zu halten, und es läuft auf demselben Agent SDK wie die interaktive CLI, laut Anthropics eigene Dokumentation zum Headless-Modus.

Am wichtigsten sind hier die Flags von Claude Code selbst, denn genau gegen sie werden Sie skripten. Zwei davon lassen einen Lauf weiterlaufen, ohne für eine Berechtigung anzuhalten, die nachts niemand erteilen kann: --allowedTools, das bestimmte Tools vorab genehmigt, und --permission-mode, das die Grundlinie für den gesamten Lauf festlegt. --max-turns begrenzt, wie viele Agent-Turns ein Lauf machen darf, bevor er mit einem Fehler endet.

--bare überspringt Hooks, Skills, Plugins, MCP-Server und Projektanweisungen wie CLAUDE.md, für einen schnelleren und deterministischeren Skriptlauf. Das heißt auch: Jede Anweisung, von der der Job abhängt, muss im Prompt oder im Befehl stehen. Der Bare-Modus liest außerdem Ihren Konto-Login nicht, deshalb die Anthropic-Dokumentation empfiehlt, einen API-Schlüssel in der Umgebung zu setzen bevor Sie ihn ausführen. Claude Code lehnt --bg rundweg ab, wenn es mit -pkombiniert wird, und lehnt --cloud genauso ab, wenn Sie ihm eine Aufgabenbeschreibung mitgeben. Es benennt den Konflikt und stoppt, statt etwas Uneindeutiges zu tun.

Ein ausgearbeiteter Aufruf, passen Sie Prompt und Tool-Liste an Ihre Aufgabe an:

claude --bare -p "Review open PRs in this repo and summarize any blockers in NOTES.md" \
  --allowedTools "Bash(gh pr list *),Bash(gh pr view *),Bash(gh pr diff *),Read,Edit" \
  --permission-mode dontAsk \
  --max-turns 8 \
  --max-budget-usd 5.00 \
  --output-format json

Passen Sie Budget und Befehlsmuster an die Aufgabe an; dieses Beispiel setzt außerdem voraus, dass die GitHub-CLI-Authentifizierung für das ausführende Konto bereits eingerichtet ist.

Wenn Sie Claude Code auf einem frischen VPS einrichten und die Anleitung zur Authentifizierung auf einer Maschine ohne Browser suchen, wird das separat behandelt in wie man Claude Code auf einem Headless-Server authentifiziert; die Kurzfassung oben reicht aus, damit ein geplanter Lauf funktioniert.

Der Modus exec von Codex CLI, beschrieben in die OpenAI-Dokumentation zum nicht-interaktiven Modus, nimmt --sandbox zur Auswahl einer Richtlinie. read-only ist die Voreinstellung, workspace-write erlaubt dem Agenten Schreibzugriff in seinem Arbeitsbereich, und --json macht aus stdout einen maschinenlesbaren Ereignisstrom statt reinen Text. Vermeiden Sie danger-full-access bei einem unbeaufsichtigten Job, es sei denn, der Prozess ist isoliert und dieses Risiko ist bewusst gewählt.

Der Headless-Modus von Gemini CLI, dokumentiert in die eigene Headless-Dokumentation des Projekts, aktiviert sich automatisch in einer Umgebung ohne TTY oder explizit mit -p. Es beendet sich mit einem eigenen Exit-Code ungleich null für einen allgemeinen Fehler, einen Eingabefehler oder ein erreichtes Turn-Limit, statt mit einem einzigen generischen Fehlercode.

Wo der Zeitplan leben sollte

Vor all dieser Einrichtungsarbeit: Vielleicht plant der Anbieter des Agenten das bereits für Sie. Claude Code bietet drei eingebaute Optionen, und eine davon kann wirklich besser passen als ein selbst verwalteter VPS.

Anthropics eigene Dokumentation zu geplanten Aufgaben stellt das als echte Dreifachwahl dar, nicht als Hierarchie mit dem VPS an der Spitze. Wenn Ihre Aufgabe keinen lokalen Zustand braucht, eine Untergrenze von einer Stunde verträgt und Sie nur Claude Code nutzen, ist Routines weniger Wartungsaufwand als das Folgende: Anthropic führt es in der Cloud aus einem frischen Klon aus, während Ihre Maschine aus ist.

/loop ist gut zu kennen, passt aber nicht zu diesem Anwendungsfall, denn es setzt eine offene, untätige Sitzung voraus, also genau die Einschränkung, die Sie loswerden wollen. Dieselbe Dokumentation nennt außerdem GitHub Actions als vierte Option, für Teams, deren Auslöser ohnehin schon in der CI liegt statt in einem Zeitplan, der an eine bestimmte Maschine gebunden ist.

Der selbst verwaltete VPS verdient seinen Platz, wenn der Job vollen Zugriff auf das lokale Dateisystem und die Werkzeuge braucht, wenn Sie denselben Mechanismus identisch über Claude Code, Codex CLI und Gemini CLI hinweg wollen, oder wenn das von Routines erlaubte Intervall zu grob ist. Eine klassische Serverless-Funktion ist hier meist unpassend, weil sie Zugangsdaten wiederherstellen, das Repository klonen und innerhalb der Laufzeitgrenzen der Plattform fertig werden muss. Ein flüchtiger CI-Runner wie GitHub Actions bleibt ein gültiger dritter Weg, wenn ein frischer Checkout pro Lauf akzeptabel ist. Wenn Sie ohnehin dauerhaft laufende Hardware ungenutzt herumstehen haben, tut es auch eine Homelab-Kiste; der Tausch ist die Zuverlässigkeit Ihres Heimnetzes und Fernzugriffs statt der eines Anbieters.

Cron oder ein systemd-Timer?

Beide Werkzeuge können denselben Befehl nach demselben Zeitplan auslösen, unterscheiden sich aber darin, was bei einem Neustart der Maschine passiert und wie viel Einrichtung jedes kostet:

Einfaches cron reicht für einen nächtlichen Job auf einer Maschine, die selten neu startet. Der Haken ist die Umgebung: cron startet mit einem minimalen PATHPATH, betritt Ihr Repository nicht für Sie und startet bereitwillig eine zweite Kopie, während die erste noch läuft. Packen Sie den Repository-Pfad, den eng gefassten Agent-Befehl und das Laden der Zugangsdaten in ein geschütztes Wrapper-Skript und verwenden Sie dann flock , um überlappende Läufe zu verhindern.

# /usr/local/bin/agent-nightly
#!/usr/bin/env bash
set -euo pipefail
export PATH=/usr/local/bin:/usr/bin:/bin
export ANTHROPIC_API_KEY="$(
  cat "$HOME/.config/agent-nightly/anthropic_api_key"
)"
cd /srv/myrepo
exec /usr/local/bin/claude --bare -p \
  "Run the nightly dependency audit and write the findings to NOTES.md" \
  --allowedTools "Bash(npm audit *),Read,Edit" \
  --permission-mode dontAsk \
  --max-turns 8 \
  --max-budget-usd 5.00 \
  --output-format json

# crontab -e
0 2 * * * /usr/bin/flock -n "$HOME/.local/state/agent-runs/nightly.lock" /usr/local/bin/agent-nightly >> "$HOME/.local/state/agent-runs/nightly.log" 2>&1

Legen Sie die Verzeichnisse für Zugangsdaten und Logs einmalig an und machen Sie das Wrapper-Skript dann ausführbar:

install -d -m 700 \
  "$HOME/.config/agent-nightly" \
  "$HOME/.local/state/agent-runs"
touch "$HOME/.config/agent-nightly/anthropic_api_key"
chmod 600 "$HOME/.config/agent-nightly/anthropic_api_key"
"${EDITOR:-nano}" \
  "$HOME/.config/agent-nightly/anthropic_api_key"
sudo chmod 755 /usr/local/bin/agent-nightly

Fügen Sie nur den API-Schlüssel in die Zugangsdaten-Datei ein. Schreiben Sie ihn nicht direkt in die crontab.

Ein systemd-Timer erfordert mehr Einrichtung und bringt Ihnen zwei Dinge, die cron nicht hat: Logging über journald ohne selbstgebaute Umleitung, und Persistent=true. Das folgende Beispiel geht davon aus, dass ein eigenes Konto agent-runner das Verzeichnis /srv/myrepobesitzt. Speichern Sie den API-Schlüssel in einer nur für root lesbaren Datei, statt ihn in die Unit einzubetten.

Pro das systemd.timer-Handbuchbedeutet das Setzen von Persistent=true bedeutet: „Die Service-Unit wird sofort ausgelöst, wenn sie mindestens einmal während der Zeit ausgelöst worden wäre, in der der Timer inaktiv war." Ein Lauf, der gestartet wäre, während Ihr VPS für ein Kernel-Update neu startete, geht also los, sobald er wieder da ist, statt bis zum nächsten geplanten Termin still zu verschwinden.

Legen Sie die nur für root lesbare Zugangsdaten-Datei an, die der Dienst nutzt:

sudo install -d -m 700 /etc/agent-nightly
sudo touch /etc/agent-nightly/anthropic_api_key
sudo chmod 600 /etc/agent-nightly/anthropic_api_key
sudoedit /etc/agent-nightly/anthropic_api_key

Fügen Sie nur den API-Schlüssel in die Datei ein.

# /etc/systemd/system/agent-nightly.service
[Unit]
Description=Nightly scoped agent run
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
User=agent-runner
Group=agent-runner
WorkingDirectory=/srv/myrepo
Environment=HOME=/home/agent-runner
Environment=PATH=/usr/local/bin:/usr/bin:/bin
LoadCredential=anthropic_api_key:/etc/agent-nightly/anthropic_api_key
ExecStart=/bin/sh -c 'export ANTHROPIC_API_KEY="$(cat "$CREDENTIALS_DIRECTORY/anthropic_api_key")"; exec /usr/local/bin/claude --bare -p "Run the nightly dependency audit and write the findings to NOTES.md" --allowedTools "Bash(npm audit *),Read,Edit" --permission-mode dontAsk --max-turns 8 --max-budget-usd 5.00 --output-format json'
StandardOutput=journal
StandardError=journal
UMask=0077

# /etc/systemd/system/agent-nightly.timer
[Unit]
Description=Run agent-nightly.service at 2am daily, catching up missed runs

[Timer]
# Uses the VPS's configured local timezone
OnCalendar=*-*-* 02:00:00
Persistent=true
Unit=agent-nightly.service

[Install]
WantedBy=timers.target

Laden Sie systemd neu, aktivieren Sie den Timer und starten Sie den Dienst einmal sofort, damit Probleme mit Zugangsdaten, Berechtigungen und Pfaden jetzt auftauchen und nicht um 2 Uhr nachts:

sudo systemctl daemon-reload
sudo systemctl enable --now agent-nightly.timer
sudo systemctl start agent-nightly.service
systemctl list-timers agent-nightly.timer
sudo journalctl \
  -u agent-nightly.service \
  -n 100 \
  --no-pager

Persistent=true ist der entscheidende Unterschied: Der Timer merkt sich einen verpassten Kalenderlauf, statt ihn stillschweigend fallen zu lassen.

Was der VPS wirklich braucht

Das ist der Teil, der Leute überrascht, die das zum ersten Mal dimensionieren: Die CLI selbst ist leichtgewichtig, weil die Inferenz auf der API des Anbieters läuft. Der Agent kann aber trotzdem lokal Builds, Tests, Paketmanager, Sprachserver und Container starten, und damit setzt die Last des Repositories die eigentliche Untergrenze.

Nehmen Sie 1 bis 2 vCPU und 2 bis 4 GB RAM mit NVMe-Speicher als Ausgangspunkt für einen leichtgewichtigen geplanten Job. Große Repositories, Compiler, Docker-Builds, Test-Suites oder parallele Läufe können deutlich mehr brauchen. Was zum Aufrüsten zwingt, ist der schwerste lokale Befehl, den der Agent ausführt, nicht das Modell hinter der API. Wenn Sie auf diesem VPS ohnehin schon Docker-Workloads betreiben und ein vollständigeres Bild vom Budget wollen, Dimensionierung und Absicherung einer Build-Maschine geht denselben Zielkonflikt für eine andere unbeaufsichtigte Arbeitslast durch.

Noch etwas, das Sie einplanen sollten: Ein unbeaufsichtigter Lauf produziert jede Nacht Logs, ob etwas schiefging oder nicht. Fügen Sie logrotate hinzu, wenn cron in eine Datei schreibt, und prüfen Sie die Aufbewahrungsgrenzen von journald, statt anzunehmen, dass die Voreinstellungen zur Platte des VPS passen.

Der ganze Ansatz hängt an einem Host, der um 2 Uhr nachts wach ist und es bleibt, egal was Ihr Laptop gerade tut. Genau dafür ist ein Linux VPS mit Root-Zugriff gebaut. Nichts schickt ihn schlafen, und Sie teilen ihn nicht mit den cron-Jobs anderer Leute.

Entwickeln Sie auf einem Linux-VPS mit Root-Zugriff, NVMe und AMD-EPYC-Power.

Linux-Pläne ansehen

Verhindern, dass ein unbeaufsichtigter Lauf schiefgeht

Der größte Unterschied zwischen einem geplanten Lauf, der funktioniert, und einem, der es nicht tut, ist, ob die Aufgabe eng genug gefasst ist, um ohne einen Menschen, der mittendrin eine Frage beantwortet, fertig zu werden. Ehrgeizige Prompts bleiben stehen und warten auf eine Entscheidung, die niemand treffen kann; enge, in sich geschlossene Aufgaben laufen durch und beenden sich sauber.

Die beiden Berechtigungs-Flags gibt es, damit ein Lauf nicht um 2 Uhr nachts an einer Abfrage hängen bleibt, aber blanker Bash Zugriff ist keine enge Leitplanke: Er kann fast alles, was das Dienstkonto kann. Bevorzugen Sie befehlsspezifische Regeln wie Bash(git status *), kombinieren Sie sie mit --permission-mode dontAsk, und lassen Sie den Dienst unter einem eigenen Nicht-Root-Konto laufen. Turn-Zahl und Ausgaben bekommen jeweils eine eigene Obergrenze: --max-turns begrenzt, wie lange der Agent umherirren darf, und --max-budget-usd deckelt, wie viel ein einzelner Lauf für API-Aufrufe ausgeben darf.

Profi-Tipp: Führen Sie den Lauf mit --output-format json aus und protokollieren Sie das Feld total_cost_usd aus jedem Aufruf mit. Das ist der sauberste Ansatzpunkt, um zu verfolgen, was ein geplanter Lauf pro Nacht tatsächlich kostet, und um zu alarmieren, wenn ein Lauf spürbar mehr kostet als die anderen. Die fünf Minuten Einrichtung lohnen sich, denn verfolgt wird Ihre Rechnung, keine Abstraktion.

Kostenüberschreitungen bei unbeaufsichtigten Läufen sind nicht hypothetisch. In einem Beitrag auf Hacker Newsberichtete ein Nutzer von einer AWS-Bedrock-Bruttorechnung über 37.901,73 $ aus einem täglichen Coding-Agent-Workflow, bei dem das Prompt-Caching nur teilweise griff und rund 6,47 Milliarden Eingabe-Token ungecacht blieben. Das passierte in einem anderen Stack, nicht im Headless-Modus von Claude Code, zeigt aber, warum Kosten-Logging und ein hartes Budget pro Lauf in den Zeitplan gehören.

Profi-Tipp: Claude Code beendet sich bei Erfolg mit Code 0 und bei einem Fehler mit einem Code ungleich null. Ein Wrapper-Skript, das den Exit-Status prüft, kann Ihnen bei einem Fehlschlag eine Benachrichtigung schicken, sodass eine schlechte Nacht am nächsten Morgen auffällt und nicht erst drei Tage später, wenn Sie zufällig hinsehen.

Lassen Sie jeden Job mindestens auf einem eigenen Branch oder in einem wegwerfbaren Worktree laufen und verlangen Sie vor dem Merge eine menschliche Prüfung. Eng gefasste Zugangsdaten, Dateisystem-Isolierung und die Kontrolle des Schadensradius auf Serverebene sind ein größeres Thema, das eine eigene Behandlung verdient statt eines angehängten Absatzes in einem Planungsleitfaden.

Erst die Leitplanken machen es sicher, den Zeitplan sich selbst zu überlassen: Der Zeitplan allein ist nicht der Sicherheitsmechanismus.

Wann cron nicht mehr reicht

Ein einzelner Prompt auf einem Timer braucht nicht mehr als das, was hier bereits beschrieben ist. Drei verkettete Schritte mit einer Bedingung, einem Retry und einer Slack-Benachrichtigung brauchen etwas anderes.

Drei Optionen sind es wert, dass man sie kennt, jede aus einem anderen Grund ein Schritt nach oben:

• Dagu ist der leichteste Schritt nach oben: eigenständige, in YAML definierte Jobs mit DAG-Abhängigkeiten, Retries und einer Web-Oberfläche, in der man sieht, was gelaufen ist.
• n8n passt am besten, wenn der Agentenlauf nur ein Knoten unter mehreren Integrationen und Benachrichtigungen ist und nicht der ganze Workflow.
• Kestra ist das schwergewichtigste der drei, gebaut für die Orchestrierung von Daten- und Infrastruktur-Pipelines, und die richtige Antwort, wenn das Einplanen des Agenten Teil einer größeren Pipeline ist statt deren Zweck.

Für Leser, die einen einzigen nächtlichen Prompt laufen lassen, sind alle drei überdimensioniert, und das sollte man klar sagen, statt Sie zu einem schwereren Setup zu überreden, als Sie brauchen. Wenn eine Kette von Schritten irgendwann eines davon rechtfertigt: Dagu, n8n, und Kestra lassen sich alle mit einem Klick bereitstellen, was genau in dem Moment praktisch ist, in dem Sie abwägen, ob der Einrichtungsaufwand sich lohnt.

Frameworks für Multi-Agenten-Orchestrierung wie LangChain oder CrewAI sind ein ganz anderes Thema: Agentensysteme bauen statt eine bereits vorhandene CLI einzuplanen.

Häufig gestellte Fragen