KiroCrew auf VPS selbst hosten: Agent dauerhaft betreiben

Warum KiroCrew auf einem VPS statt auf einem Laptop selbst hosten

KiroCrew lohnt sich nur auf einem Rechner, der nie in den Ruhezustand wechselt. Ein VPS ist daher der richtige Ort dafür, ein Laptop dagegen nicht. KiroCrew speichert Sitzungsverlauf, semantischen Speicher, geplante Jobs und die Genehmigungswarteschlange auf der Festplatte. Beim Neustart des Prozesses lädt es diese Daten wieder. Das hilft nicht, wenn der Prozess um 03:00 Uhr wegen eines fälligen geplanten Jobs nicht läuft. Ein geschlossenes Laptop führt den Prozess nicht aus.

KiroCrew ist ein Open-Source-Agent-Arbeitsbereich des Kiro-Teams. Die Lizenz ist Apache 2.0. Die ersten öffentlichen Releases erschienen Anfang August 2026. Ein Prozess namens Gateway verwaltet den Zustand und stellt ein Web-Dashboard auf Port 5476 bereit. Sie erreichen dieses Gateway über das Dashboard, über die kirocrew CLI oder über einen Chat-Kanal wie Slack. Nur das Gateway wird von Ihnen selbst gehostet. In dieser Anleitung geht es daher darum, es dauerhaft auszuführen, vom öffentlichen Internet fernzuhalten und nach einem fehlerhaften Upgrade wiederherstellen zu können.

Vor dem Start sind zwei Punkte wichtig. KiroCrew verwendet kiro-cli. Dafür ist eine einmalige Anmeldung mit einem Kiro-Konto erforderlich. Die Agent-Inferenz wird über einen Kiro-Tarif abgerechnet. Daher handelt es sich im August 2026 nicht um eine Offline-Konfiguration. Das Projekt ist außerdem erst wenige Wochen alt. Gehen Sie davon aus, dass Sie irgendwann ein Rollback durchführen müssen, und installieren Sie es so, dass dies möglich ist. Wenn Sie bisher noch keinen Agent auf einem Server betrieben haben, behandelt einen Coding-Agent auf einem VPS betreiben die Grundlagen, auf denen diese Anleitung aufbaut.

Was KiroCrew benötigt und wo sein Zustand gespeichert wird

Eine native Installation benötigt Python 3.10 oder neuer (das Projekt empfiehlt 3.12), Node.js 18 oder neuer, wenn Sie das Dashboard aus dem Quellcode erstellen, sowie kiro-cli. kiro-cli wird beim ersten Start installiert und meldet Sie automatisch an. Bei der Container-Installation ist nichts davon auf dem Host erforderlich. Sie benötigt Docker. Das ist der wichtigste Grund, sie zu bevorzugen.

Der Zustand wird in ~/.kiro/crew gespeichert. Die Umgebungsvariable KIROCREW_HOME verschiebt ihn an einen anderen Speicherort. Darin befinden sich:

• config.json: Gateway-Einstellungen und Zugangsdaten für Chat-Kanäle.
• .env: Secrets.
• workspace/memory/: Einstellungen, Projektnotizen und Chatverlauf.
• memory.db und memory_index.db: die semantischen und die Volltextindizes.
• models/: das beim ersten Start heruntergeladene Embedding-Modell.
• gateway.log und security_events.jsonl: das Laufzeitprotokoll und das Protokoll der Sicherheitsereignisse.

Dieses Verzeichnis ist die Installation. Kopieren Sie es auf einen neuen VPS, ist Ihr Agent umgezogen. Deshalb ist der folgende Abschnitt zu Backups wichtiger als der Installationsabschnitt.

Planen Sie eher den Speicherplatz als den Arbeitsspeicher. Das Gateway ist ein Python-Prozess. Was den Server tatsächlich belastet, sind die Aufgaben, die der Agent ausführt, beispielsweise ein Build oder eine Testsuite. Das Zustandsverzeichnis wächst mit dem Chatverlauf, und das Embedding-Modell wird beim ersten Start heruntergeladen. Messen Sie die Größe daher nach einigen Wochen auf Ihrem eigenen Server mit du -sh ~/.kiro/crew, statt einer Zahl zu vertrauen, die im ersten Monat eines Projekts veröffentlicht wurde.

Welchen der drei Installationswege sollten Sie verwenden

Das Projekt veröffentlicht drei Varianten. Das Installationsskript in einer Zeile lädt ein Wheel herunter und legt kirocrew in Ihrem PATH ab:

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh

Es akzeptiert ein Channel-Flag und ein Versions-Flag:

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --channel insider
curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --version 0.1.3

Das Container-Image wird unter ghcr.io/kirodotdev/kirocrew veröffentlicht, für linux/amd64 und linux/arm64 unter jedem Tag. Der Quellcode-Build besteht aus git clone und make build. Er ist für Personen gedacht, die den Code ändern, nicht für Personen, die ihn ausführen.

Verwenden Sie den Container. Bei einer nativen Installation liegen Python-Pakete, Node und kiro-cli auf demselben Host wie Ihre anderen Dienste. Wenn ein Upgrade fehlschlägt, müssen Sie die Änderungen daher manuell zurücknehmen. Der Container hält die Laufzeitumgebung in einem Image und den Zustand in einem Volume. Für ein Rollback müssen Sie dadurch nur den Tag ändern und den Container neu starten.

Das Image auf einen Release-Tag festlegen, nicht auf stable

Das eigene Beispiel des Projekts verwendet den Tag stable:

docker run -d --name kirocrew \
  -p 127.0.0.1:5476:5476 \
  -v kirocrew-home:/home/kirocrew \
  ghcr.io/kirodotdev/kirocrew:stable

stable ist ein veränderlicher Tag. Er verweist jeweils auf den neuesten stabilen Release. Dadurch kann der nächste Pull die ausgeführte Version ändern, ohne dass Sie dies festlegen. Außerdem lässt sich dem Tag nicht entnehmen, welche Version verwendet wurde. Versions-Tags sind unveränderlich. Verwenden Sie daher einen solchen Tag. Der neueste Release vom 6 August 2026 ist 0.1.3, veröffentlicht am 5 August 2026. Es gibt außerdem den Tag nightly. Bei einem Projekt in diesem frühen Entwicklungsstadium bedeutet das, dass sich der Code heute Morgen geändert hat.

Schreiben Sie /opt/kirocrew/compose.yaml:

services:
  kirocrew:
    image: ghcr.io/kirodotdev/kirocrew:0.1.3
    container_name: kirocrew
    restart: unless-stopped
    ports:
      - "127.0.0.1:5476:5476"
    volumes:
      - kirocrew-home:/home/kirocrew

volumes:
  kirocrew-home:

Starten Sie den Container. Prüfen Sie anschließend den Health-Endpunkt, den das Image auch für seinen eigenen HEALTHCHECK verwendet:

cd /opt/kirocrew
docker compose up -d
docker compose ps
curl -s http://127.0.0.1:5476/api/health

docker compose ps sollte den Container innerhalb von etwa einer Minute als gesund melden. /api/health antwortet ohne Token. Das gilt auch für /api/live und /api/ready. Dadurch können diese Endpunkte als Prüfungen verwendet werden. Wenn der Status bei starting bleibt, lesen Sie zuerst docker logs kirocrew, bevor Sie etwas ändern. Beim ersten Start wird das Embedding-Modell heruntergeladen. Eine langsame Verbindung verlängert daher den ersten Start.

Mit systemd dauerhaft ausführen

restart: unless-stopped startet den Container nach einem Absturz und nach einem Reboot erneut, sofern Docker selbst beim Booten gestartet wird. Eine Unit-Datei macht diese Abhängigkeit explizit und stellt einen einzelnen Befehl bereit, mit dem Sie den gesamten Stack vor einem Backup stoppen können. Einen Docker-Compose-Stack beim Booten starten beschreibt das allgemeine Vorgehen. Die Variante für KiroCrew sieht in /etc/systemd/system/kirocrew.service so aus:

[Unit]
Description=KiroCrew gateway
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/kirocrew
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now kirocrew
systemctl status kirocrew

systemctl status kirocrew sollte active (exited) anzeigen. Das ist das erwartete Ergebnis für diese Unit. Type=oneshot mit RemainAfterExit=yes ist an dieser Stelle korrekt, weil docker compose up -d zurückkehrt, sobald der Container gestartet wurde: systemd überwacht, dass der Stack aktiv ist, nicht einen Vordergrundprozess. Verwenden Sie stattdessen Type=simple, erkennt systemd, dass der Befehl sofort beendet wurde, markiert den Dienst als beendet und gibt entweder auf oder startet ihn abhängig von Ihrer Einstellung Restart= wiederholt neu. Bei einer nativen Installation stellt das Projekt mit kirocrew service install ein entsprechendes Gegenstück bereit. Dieses schreibt /etc/systemd/system/kirocrew.service und führt das Gateway unter Ihrem Benutzerkonto aus. Führen Sie nicht beide Units aus. Die ausführlichere Behandlung dieses Themas finden Sie unter systemd-Dienste und Timer auf einem VPS.

Erster Start: anmelden und ein Dashboard-Token erstellen

Der Container startet das Gateway, aber die Agent-Laufzeitumgebung ist noch nicht angemeldet. Melden Sie sich im Container an:

docker exec -it kirocrew kiro-cli login

Dabei werden ein Gerätecode und eine URL ausgegeben. Öffnen Sie die URL in Ihrem eigenen Browser. Erstellen Sie anschließend ein Dashboard-Token:

docker exec kirocrew kirocrew token --ttl 2h

Die Dashboard-URL lautet http://localhost:5476/?token=<the token>. Tokens laufen ab: Sitzungen sind standardmäßig eine Stunde gültig. Die dokumentierte maximale Gültigkeitsdauer beträgt zwanzig Stunden. Wenn das Dashboard leer bleibt oder Sie direkt wieder abmeldet, ist das Token meist abgelaufen. Erstellen Sie dann ein neues Token. Fügen Sie ein Token niemals in ein Ticket oder eine Chatnachricht ein. Wer das Token besitzt, kann Ihren Agenten steuern.

Dashboard über SSH erreichen und Port 5476 niemals veröffentlichen

Sehen Sie sich die Bind-Adresse im Beispiel des Projekts erneut an: -p 127.0.0.1:5476:5476. Innerhalb des Containers lauscht das Gateway auf 0.0.0.0, weil es über die Port-Zuordnung erreichbar sein muss. Die Zuordnung selbst veröffentlicht den Port jedoch nur auf dem Loopback-Interface des Hosts. Entfernen Sie das Präfix 127.0.0.1:, ist das Gateway für jeden, der diesen Port scannt, im öffentlichen Internet erreichbar. Eine Firewall-Regel schützt Sie ebenfalls nicht: Docker veröffentlicht Ports, indem es DNAT-Regeln schreibt, die vor der Filterung durch ufw ausgewertet werden. Daher bewirkt ufw deny 5476 bei einem veröffentlichten Port nichts. Docker-Ports umgehen ufw erläutert diesen Mechanismus.

Leiten Sie den Port stattdessen von Ihrem Laptop über SSH weiter:

ssh -N -L 5476:127.0.0.1:5476 you@your-server.example.com

Lassen Sie diesen Prozess laufen und öffnen Sie lokal http://localhost:5476/?token=<the token>. Damit die Weiterleitung bei jeder Verbindung automatisch eingerichtet wird, tragen Sie sie in ~/.ssh/config ein:

Host your-server.example.com
    LocalForward 5476 127.0.0.1:5476

Wenn Port 5476 auf Ihrem Laptop bereits verwendet wird, ändern Sie nur die Zahl auf der linken Seite: ssh -N -L 45476:127.0.0.1:5476 you@your-server.example.com. Öffnen Sie anschließend http://localhost:45476/?token=....

Über einen Tunnel müssen Sie mit folgendem dokumentierten Verhalten rechnen: Das Gateway behandelt weitergeleitete Anfragen als remote. Daher verweigern die Endpunkte zum Schreiben der Konfiguration und zum Anzeigen von Geheimnissen diese Anfragen im Dashboard. Wenn eine Einstellungsänderung über SSH nicht gespeichert werden kann, ist das dieses Verhalten und kein Fehler. Bearbeiten Sie die Konfiguration stattdessen auf dem Host:

docker cp kirocrew:/home/kirocrew/.kiro/crew/config.json .
# edit config.json here
docker cp config.json kirocrew:/home/kirocrew/.kiro/crew/config.json
docker exec -u 0 kirocrew chown kirocrew:kirocrew /home/kirocrew/.kiro/crew/config.json
docker restart kirocrew

Für den Zugriff per Smartphone verweist das Projekt auf tailscale serve von Tailscale. Dadurch bleibt das Dashboard innerhalb Ihres eigenen Tailnet und ist nicht unter einem öffentlichen Hostnamen erreichbar. Verwenden Sie diese Lösung bevorzugt gegenüber einem öffentlichen Reverse Proxy. Das Token wird in der URL übertragen. Eine URL wird entlang ihres Pfads in jedes Access-Log geschrieben.

Geben Sie dem Agenten den kleinstmöglichen Wirkungsbereich

Der Container prüft beim ersten Start, ob die Sandbox unterstützt wird. Das Ergebnis entscheidet, ob Agenten überhaupt etwas ausführen können. Wenn die Namespace-Isolierung verfügbar ist, werden die Subprozesse des Agenten isoliert ausgeführt. Ist sie nicht verfügbar und KIROCREW_ALLOW_UNSANDBOXED=1 nicht gesetzt, wird die Ausführung verweigert, statt sie ohne Isolierung zu starten. Ein Gateway, das gesund wirkt, während jede Aufgabe hängen bleibt, ist daher meist auf dieses Problem zurückzuführen. Die Entscheidung steht nach dem ersten Lauf in docker logs kirocrew. Das Projekt stellt außerdem ein seccomp-Profil (Secure Computing Mode) bereit, das Sie anwenden können:

curl -fsSL https://raw.githubusercontent.com/kirodotdev/KiroCrew/main/docker/seccomp/kirocrew-seccomp.json \
  -o /opt/kirocrew/kirocrew-seccomp.json

    security_opt:
      - seccomp:./kirocrew-seccomp.json

Wenn Sie KIROCREW_ALLOW_UNSANDBOXED=1 setzen, muss klar sein, was sich dadurch ändert: Der Container ist nun die einzige Grenze zwischen dem Agenten und Ihrem Server. Die Warnung des Projekts sollte vollständig wiederholt werden. Binden Sie keine Hostpfade ein, die Sie dem Agenten nicht direkt übergeben würden. In der Praxis schließt das den Docker-Socket, jede Bind-Mount-Einbindung von / sowie jedes Verzeichnis aus, das die Daten eines anderen Dienstes enthält.

Der restliche Rahmen gilt für jeden Agenten, der Befehle ausführen darf. Beschränken Sie seine Zugangsdaten auf das eine Repository oder den einen Bucket, den er benötigt. Verwenden Sie niemals ein persönliches Token mit kontoweiten Berechtigungen. Führen Sie ihn als dedizierten Benutzer aus, dessen Home-Verzeichnis keine anderen Daten enthält. Genau dafür sind Benutzer mit geringsten Berechtigungen auf einem VPS gedacht. Wenn der Agent Code schreibt und diesen anschließend ausführt, geben Sie ihm eine Maschine, die er beschädigen darf: eine kurzlebige VM für Coding-Agenten bildet eine stärkere Grenze als jedes Flag in dieser Compose-Datei, weil Sie sie löschen können, statt sie bereinigen zu müssen. Derselbe Grundsatz gilt für den sicheren Betrieb von OpenClaw auf einem VPS und das Self-Hosting des Hermes-Agenten auf einem VPS. Auch geplante Aufgaben verursachen Kosten, während Sie schlafen, da die Inferenz Ihrem Kiro-Tarif belastet wird. Legen Sie daher die unter Kostenkontrolle für einen KI-Agenten auf einem VPS beschriebenen Limits fest, bevor Sie einen nächtlichen Job hinzufügen.

Back up the state volume before every upgrade

Find the real volume name first. Compose prefixes named volumes with the project name, which defaults to the directory name, so the volume declared as kirocrew-home in /opt/kirocrew/compose.yaml is created as kirocrew_kirocrew-home:

docker volume ls

Stop the gateway before copying anything. memory.db and memory_index.db are SQLite databases, and copying a database while it is being written can capture a half-written transaction, which restores as a corrupt file. The project's own migration instructions say the same: move memory only while the gateways are stopped.

sudo systemctl stop kirocrew
docker run --rm -v kirocrew_kirocrew-home:/data:ro -v "$PWD":/backup \
  alpine tar czf /backup/kirocrew-2026-08-06.tgz -C /data .
sudo systemctl start kirocrew

Copy the archive off the box. Restoring is the same command with the container stopped and tar xzf in place of tar czf:

sudo systemctl stop kirocrew
docker run --rm -v kirocrew_kirocrew-home:/data -v "$PWD":/backup \
  alpine tar xzf /backup/kirocrew-2026-08-06.tgz -C /data
sudo systemctl start kirocrew

Moving to a new host is a different job from restoring in place, and the project is specific about it. Chat history and project notes under workspace/memory/ carry over, and so do the two database files and config.json. PID files, the security event log and .env are tied to the old host, so leave them behind and enter the secrets again on the new box.

Wie führen Sie ein fehlerhaftes Upgrade zurück?

Das Upgrade dauert nur kurz. Es ist nur deshalb sicher, weil Sie eine Version festgelegt haben. Erstellen Sie zuerst das Backup und ändern Sie anschließend den Tag:

sudo systemctl stop kirocrew
# take the backup here, as above
sudo nano /opt/kirocrew/compose.yaml   # set the new image tag
sudo systemctl start kirocrew
docker compose -f /opt/kirocrew/compose.yaml ps
curl -s http://127.0.0.1:5476/api/health

docker compose up -d lädt das Image herunter, wenn es noch nicht auf dem System vorhanden ist. Daher besteht das gesamte Upgrade aus der Änderung des Tags. Für ein Rollback führen Sie dieselben Schritte mit der alten Versionsnummer aus. Dadurch erhalten Sie genau das Image, das zuvor verwendet wurde, weil Versions-Tags unveränderlich sind.

Die Binärdatei lässt sich problemlos zurücksetzen. Beim Zustand kann dies anders sein. Ein neueres Gateway kann config.json neu schreiben oder die Speicherdatenbanken in eine Form migrieren, die ein älteres Gateway nicht lesen kann. Seit August 2026 ist kein dokumentierter Downgrade-Pfad verfügbar. Wenn das ältere Image startet und sich anschließend ungewöhnlich verhält, sollten Sie dies nicht debuggen. Stoppen Sie es, stellen Sie das vor dem Upgrade erstellte Backup wieder her und starten Sie erneut. Genau deshalb wird das Backup zuerst erstellt. Aus demselben Grund funktioniert die Gewohnheit, jetzt zu aktualisieren und erst später ein Backup zu erstellen, bei einem so jungen Projekt nicht.

Was hier nicht bewiesen ist

Seien Sie ehrlich hinsichtlich des Alters dieser Software. Die Version 0.1.3 ist zum Zeitpunkt der Erstellung erst wenige Tage alt. Die Release Notes bestehen aus automatisierten Changelog-Links und nicht aus Migrationshinweisen. Erfahrungen mit Upgrades gibt es noch nicht. Nichts in dieser Anleitung ist ein langfristiges Ergebnis. Betrachten Sie Speicherwachstum, Datenbankgröße und die Zuverlässigkeit des Schedulers daher als Werte, die Sie auf Ihrem eigenen System messen müssen, und nicht als Eigenschaften, die Sie voraussetzen können.

Zwei Verhaltensweisen sollten Sie selbst testen, bevor Sie sich darauf verlassen. Prüfen Sie erstens, ob ein Downgrade den von einer neueren Version geschriebenen Zustand lesen kann. Testen Sie dies an einer Kopie des Volumes, solange ein Fehler keine Auswirkungen hat, und nicht während eines Ausfalls. Prüfen Sie zweitens, wie sich das Gateway verhält, wenn die Kiro-Anmeldung abläuft, während ein geplanter Job ausgeführt werden soll. Beide Fälle sind typische Schwachstellen eines jungen Projekts, die zwischen Releases unauffällig behoben werden. Beide lassen sich jetzt mit geringem Aufwand prüfen.

FAQ

Warum wird das KiroCrew-Dashboard nicht über die öffentliche IP-Adresse meines Servers geöffnet?

Der veröffentlichte Beispielbefehl bindet den Port an das Loopback-Interface. -p 127.0.0.1:5476:5476 ordnet den Container-Port ausschließlich der Loopback-Adresse des Hosts zu. Das ist beabsichtigt. Greifen Sie darauf zu, indem Sie den Port mit ssh -N -L 5476:127.0.0.1:5476 you@your-server über SSH weiterleiten. Öffnen Sie anschließend http://localhost:5476/?token=<token> auf Ihrem Laptop. Wenn Sie das Präfix 127.0.0.1: entfernen, ist das Gateway im öffentlichen Internet erreichbar. Eine Firewall-Regel verhindert das nicht, weil Docker die DNAT-Regeln für veröffentlichte Ports auswertet, bevor ufw den Datenverkehr filtert.

Wo speichert KiroCrew seine Daten, und was sollte ich sichern?

Alle Daten liegen unter ~/.kiro/crew. Im Container-Image entspricht das /home/kirocrew/.kiro/crew. Mit KIROCREW_HOME verschieben Sie dieses Verzeichnis. Sichern Sie bei gestopptem Gateway das gesamte Verzeichnis oder das gesamte Docker-Volume. Bei memory.db und memory_index.db handelt es sich um SQLite-Datenbanken. Eine Kopie während eines Schreibvorgangs des Gateways kann daher inkonsistent sein. Beim Umzug auf einen neuen Host nehmen Sie workspace/memory/, die beiden Datenbankdateien und config.json mit. PID-Dateien, das Sicherheitsereignisprotokoll und .env gehören dagegen zum alten Host.

Sollte ich das Tag stable oder ein Versions-Tag verwenden?

Verwenden Sie ein Versions-Tag. stable ändert sich bei jeder Veröffentlichung einer neuen Version. Die ausgeführte Version kann sich daher beim nächsten Pull unbemerkt ändern. Außerdem sagt das Tag selbst nichts darüber aus, welche Version gerade ausgeführt wird. Versions-Tags wie 0.1.3 sind unveränderlich. Genau deshalb funktionieren Rollbacks: Sie tragen die alte Versionsnummer wieder ein und erhalten dasselbe Image. Am 6. August 2026 ist 0.1.3 die neueste Version.

Warum verweigert mein Agent die Ausführung aller Befehle?

Der Container prüft beim ersten Start, ob eine Sandbox unterstützt wird. Wenn er Agent-Subprozesse nicht isolieren kann und KIROCREW_ALLOW_UNSANDBOXED=1 nicht gesetzt ist, verweigert er deren Ausführung, statt sie ohne Einschränkung zu starten. Das Gateway wirkt dann betriebsbereit, während jede Aufgabe hängen bleibt. docker logs kirocrew zeigt die bei diesem ersten Start getroffene Sandbox-Entscheidung. Wenn Sie die Variable setzen, ist der Container die einzige Grenze zwischen dem Agenten und dem Host. Mounten Sie in diesem Fall nichts, was Sie dem Agenten nicht direkt übergeben würden.

Benötige ich ein Kiro-Konto, um KiroCrew selbst zu hosten?

Ja, Stand August 2026. KiroCrew ist freie Software unter der Apache-2.0-Lizenz. Die Software steuert jedoch kiro-cli, wofür eine einmalige Anmeldung erforderlich ist. Die Agenteninferenz wird über einen Kiro-Tarif abgerechnet. Führen Sie im Container docker exec -it kirocrew kiro-cli login aus und bestätigen Sie den Gerätecode in Ihrem Browser. Bis diese Anmeldung abgeschlossen ist, startet das Gateway und das Dashboard wird geladen. Der Agent hat jedoch kein Modell, mit dem er kommunizieren kann.