Rakazo selbst hosten: KI-Bot auf dem eigenen VPS
Rakazo auf dem eigenen VPS betreiben: Node 22, pnpm, PostgreSQL und Graphile Worker per Docker Compose, Sandbox-Anbieter, Schlüsselverwaltung und realistische Servergröße.
Was beim Self-Hosting von Rakazo tatsächlich läuft
Self-Hosting von Rakazo bedeutet, fünf Komponenten auf einem Linux-Server zu betreiben: PostgreSQL, einen Graphile-Worker-Prozess, die API, die Webanwendung und einen Sandbox-Container, der als Computer der Bots dient. Rakazo ist eine Open-Source-Alternative zu Grok Bot, die von elie222 unter der Apache-2.0-Lizenz veröffentlicht wird. Jeder Bot hat eigene Unterhaltungen, eigenen Speicher, eigene Routinen und eine eigene Historie. Er verwendet gemeinsam mit den anderen Bots des Workspace einen Team Computer, sofern ihm kein Private Computer zugewiesen wurde, und kann weitere Bots oder kurzlebige Subagenten starten. Wenn Begriffe wie Speicher, Subagent und Tool-Aufruf in diesem Zusammenhang ungewohnt sind, lohnt sich ein schrittweiser Einstieg in die tatsächliche Arbeitsweise von Agents zunächst für einen Nachmittag. Die meisten folgenden Einstellungen sind erst verständlich, wenn Sie sich vorstellen können, was ein Bot beim Aufwachen ausführt.
Genau deshalb gehört Rakazo auf einen VPS (virtual private server) und nicht auf einen Desktop. Ein Bot, der Speicher hält und geplante Aufgaben ausführt, muss erreichbar sein, während Sie schlafen. Ein Laptop, der in den Suspend-Modus wechselt, unterbricht die Warteschlange.
Rakazo bezeichnet sich auch im Oktober 2026 noch als Beta, obwohl inzwischen Releases mit stabilen Versionsnummern veröffentlicht werden. Betrachten Sie dies daher als funktionierende Einrichtung und nicht als fertiges Appliance-System. Der gesamte Stack basiert auf TypeScript: React 19 und Vite für die Webanwendung, Hono für die API, Postgres mit Prisma, Better Auth für Konten und Graphile Worker für Hintergrundaufgaben. Graphile Worker speichert seine Warteschlange in Postgres. Deshalb benötigen Sie weder Redis noch einen zweiten Datenspeicher. .env.example setzt WAKEUP_DRIVER=graphile, sodass das Aufwachen eines Bots einem von Postgres unterstützten Job entspricht. Wenn Sie Postgres stoppen, werden auch alle geplanten Aktionen der Bots beendet. Wenn Sie stattdessen einen Agent aus einzelnen Komponenten zusammenstellen möchten, ist der Bau eines eigenen Agents aus Komponenten der andere Weg.
Warum ein Plan mit 1 GB dafür nicht ausreicht
Zählen Sie die Prozesse. Postgres ist einer. Die API läuft als Node-Prozess. Der Worker ist ein zweiter. Die Webanwendung ist ein dritter. Der Sandbox-Supervisor ist ein vierter. Danach kommt der Computer der Bots: Standardmäßig ist das ein gemeinsamer Team Computer-Container mit einem grafischen Linux-Desktop, einem eigenen X-Display und einem Chrome-Prozess für jeden aktiven Bot.
Die Self-Hosting-Dokumentation des Projekts nennt inzwischen keine Host-Größe mehr. Die unter v0.3.5 am 27. Oktober 2026 geprüfte Dokumentation führt nur Softwareanforderungen auf. Sie nennt jedoch ein Limit pro Computer: Bei Docker-Sandboxes ist RAKAZO_COMPUTER_MEMORY standardmäßig auf 2g und RAKAZO_COMPUTER_CPUS auf 2 gesetzt. Dieses Limit gilt für jeden Computer, nicht für jeden Bot. Jeder Workspace erhält standardmäßig einen Team Computer. Jeder aktive Team-Bot führt seinen Desktop und Browser darin aus. Alle teilen sich daher diese 2 GB und zwei Cores. Nur ein Bot, der auf einen Private Computer verschoben wurde, erhält einen eigenen Container mit einem eigenen Limit. Setzen Sie SANDBOX_PROVIDER=docker, werden diese Desktops zusätzlich zur Control Plane auf Ihrem VPS ausgeführt. Damit sind 4 GB eher eine Untergrenze als ein Zielwert. Beginnen Sie mit 8 GB, wenn mehr als ein Bot aktiv bleiben soll. Erhöhen Sie RAKAZO_COMPUTER_MEMORY, damit der gemeinsame Computer diesen Speicher tatsächlich nutzen kann. Messen Sie die reale Auslastung mit docker stats, während die Bots arbeiten. Der Browser innerhalb der Sandbox verändert den Speicherbedarf maßgeblich. Ein Datenblatt liefert Ihnen daher keine verlässliche Angabe. Um zu verhindern, dass ein kleiner Server gleichzeitig zu viele Browser ausführt, setzen Sie einen positiven Wert für SANDBOX_TEAM_SCREEN_LIMIT. Dieser begrenzt die aktiven Desktops auf einem Docker Team Computer. Der ausgelieferte Wert 0 hebt die Begrenzung auf. Wenn der Speicher insgesamt knapp ist, akzeptiert RAKAZO_COMPUTER_MEMORY auch einen kleineren Wert wie 1536m. Die allgemeine Methode zur Dimensionierung eines Servers für Agent-Aufgaben wird unter wie viel RAM und CPU ein Agent-VPS tatsächlich benötigt ausführlich anhand von Messungen beschrieben.
Eine Einstellung verhindert, dass sich die Situation verschärft. .env.example wird mit SANDBOX_IDLE_MS=600000 ausgeliefert. Der Kommentar besagt, dass Computer nach dieser Anzahl inaktiver Millisekunden pausiert oder beendet werden. Nach zehn Minuten Inaktivität wird der Computer entfernt. Der kleinste akzeptierte Wert ist 30000. Mit 0 wird der Leerlaufschlaf deaktiviert. Derselbe Kommentar empfiehlt für Docker-Self-Hosting den Wert 0, weil ein inaktiver Computer dort keine Kosten verursacht. Dadurch bleiben Anwendungen mit langer Laufzeit und Sitzungen aktiv. Das spart zwar Geld, aber keinen Speicher. Lassen Sie den Timer auf einem kleinen VPS aktiviert. Andernfalls bleibt jeder gestartete Computer aktiv, einschließlich jedes darin ausgeführten Browsers.
Auch der Speicherplatz muss berücksichtigt werden. Das Sandbox-Image, die Node-Module und das Postgres-Volume verwenden denselben Datenträger. Daher sind 40 GB ein sinnvoller Ausgangswert.
Version vor dem Klonen festlegen
Rakazo entwickelt sich schnell weiter, und main ist kein Release. Stand 9 November 2026 ist v0.8.0, veröffentlicht am 4 November 2026, als Latest gekennzeichnet. Diese Anleitung bleibt auf v0.3.5 festgelegt, veröffentlicht am 25 October 2026.
git clone https://github.com/elie222/rakazo.git
cd rakazo
git checkout f31e3c0699f086d663637c4107858c238a086fb3
git log -1 --format='%H %ci'Auf diesen Commit verweist v0.3.5. Legen Sie den Commit statt des Branches oder Tags fest. Ein Branch ändert sich beim nächsten git pull unter Umständen, und ein Tag ist eine verschiebbare Bezeichnung, die ein Maintainer auf einen anderen Commit setzen kann. Daher identifiziert keiner von beiden einen Tree, zu dem Sie zurückkehren können. Ein Commit-Identifier kann sich nicht ändern. Notieren Sie ihn zusammen mit den anderen Serverdaten. Wenn ein Upgrade etwas beschädigt, besteht die schnelle Lösung in git checkout <old commit> und einem erneuten Build. Das funktioniert nur, wenn Sie wissen, welcher Commit funktioniert hat. Die festgelegte README bezeichnet Rakazo als Beta. Deshalb lohnt sich die genaue Festlegung trotz des geringen Aufwands. Bei einem Projekt mit einer langen Reihe bewusst veröffentlichter Releases können Sie stattdessen einen veröffentlichten Tag verwenden. Das macht beispielsweise ein kleinerer Self-Hosting-Stack wie openGym.
Anforderungen: Node 22, pnpm 9 und Docker
node -v
pnpm -v
docker --versionpackage.json deklariert "engines": { "node": "^22.22.2 || ^24.0.0 || >=26.0.0" } und "packageManager": "pnpm@9.15.0". Daher muss node -v v22.22.2 oder eine spätere 22.x-Version, ein beliebiges v24 oder v26 und höher ausgeben. Ein v22 älter als 22.22.2 liegt außerhalb dieses Bereichs. In der README steht außerdem ausdrücklich, dass Node.js 23.x und 25.x nicht unterstützt werden. Installieren Sie eine unterstützte Node-Version über NodeSource oder nvm. Corepack ist in Node 22 und 24 enthalten. Ab Node 26 müssen Sie Corepack zuerst mit npm install -g corepack installieren. Aktivieren Sie anschließend pnpm:
corepack enable
corepack prepare pnpm@9.15.0 --activateDocker Engine zusammen mit dem compose-Plugin deckt die übrigen Anforderungen ab. Die Dokumentation zum Self-Hosting verlangt Docker Engine 26 oder neuer sowie API 1.45 oder neuer für Unterpfade von Bot-Home-Volumes. Außerdem werden curl und OpenSSL benötigt. Ihr Benutzer muss ebenfalls auf den Daemon zugreifen können. Wenn docker ps mit permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock antwortet, fügen Sie Ihren Benutzer der Gruppe docker hinzu und öffnen Sie eine neue Login-Shell. Machen Sie sich vorher klar, welche Berechtigungen das verleiht: Die Mitgliedschaft in docker entspricht Root-Rechten auf dem Rechner, weil jedes Mitglied dieser Gruppe einen Container starten kann, der das Host-Dateisystem einbindet.
.env konfigurieren und anschließend Postgres starten
cp .env.example .env
chmod 600 .envVor dem Start müssen mehrere Werte geändert werden. .env.example liefert BETTER_AUTH_SECRET=replace-with-32-plus-character-secret, ENCRYPTION_KEY=replace-with-64-random-hex-characters, SCREEN_PROXY_SECRET=replace-with-32-plus-character-screen-proxy-secret und SANDBOX_SUPERVISOR_TOKEN=replace-with-32-plus-character-supervisor-token mit und lässt POSTGRES_PASSWORD und POSTGRES_APP_PASSWORD leer. Jeder dieser Platzhalter ist im Repository veröffentlicht. Ein Deployment, das einen davon unverändert übernimmt, verwendet ein Geheimnis, das jeder lesen kann. Vergeben Sie für jeden Platzhalter einen eigenen zufälligen Wert. ENCRYPTION_KEY muss aus 64 zufälligen Hexadezimalzeichen bestehen. Genau das gibt openssl rand -hex 32 aus. Die anderen Geheimnisse benötigen 32 oder mehr Zeichen. Führen Sie dafür die Base64-Zeile jeweils einmal aus. Für die beiden Postgres-Passwörter fordert die Self-Hosting-Dokumentation URL-sichere Werte. Diese liefert die letzte Zeile. Führen Sie sie daher ebenfalls jeweils einmal aus. Die Datenbank hat zwei Logins. DATABASE_MIGRATION_URL wird mit postgres://rakazo:REPLACE_WITH_POSTGRES_PASSWORD@127.0.0.1:5433/rakazo ausgeliefert. Das ist der Benutzer, der Migrationen ausführt. DATABASE_URL wird mit postgres://rakazo_app:REPLACE_WITH_POSTGRES_APP_PASSWORD@127.0.0.1:5433/rakazo ausgeliefert. Das ist das eigene Login der Anwendung. Es hat keine Superuser-Rechte und unterliegt der Row-Level-Security. Tragen Sie jedes Passwort in seine eigene URL ein. pnpm db:migrate erstellt das Login rakazo_app mit dem von Ihnen festgelegten Passwort.
openssl rand -base64 48
openssl rand -hex 32
openssl rand -hex 24Starten Sie anschließend nur die Datenbank und führen Sie die Migrationen aus.
docker compose --env-file .env -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.postgres-host.yml up postgres -d
pnpm install
pnpm db:generate
pnpm db:migrate
pnpm sandbox:buildpnpm sandbox:build erstellt das Bot-Computer-Image, das in package.json als docker build -t rakazo/computer:local infra/sandboxes/computer definiert ist. Es handelt sich um ein grafisches Image. Der erste Build lädt daher viele Daten herunter und dauert entsprechend lange. Prüfen Sie mit docker image ls rakazo/computer, ob es vorhanden ist. Der Befehl sollte eine Zeile ausgeben.
Die zentrale Compose-Datei veröffentlicht überhaupt keinen Postgres-Port. Das docker-compose.postgres-host.yml-Overlay in diesem Befehl veröffentlicht ihn als 127.0.0.1:5433. Der Port ist nur über Loopback erreichbar. Dadurch können hostseitige Tools wie pnpm db:migrate und pnpm dev darauf zugreifen. Lassen Sie diese Einstellung unverändert. Compose startet Postgres nicht ohne ein POSTGRES_PASSWORD in .env. Ein aus dem Internet erreichbarer Postgres-Port ermöglicht jedoch Passwortangriffe. Die Compose-Datei für die Produktion liest dieselbe Variable und veröffentlicht keinen Datenbankport.
Der erste Start
pnpm devDadurch werden standardmäßig vier Komponenten gestartet: die API auf Port 3100, der Graphile Worker, die Vite-Webanwendung auf 5173 und der Sandbox-Supervisor auf 7091. Wenn diese Ports belegt sind, wählt pnpm dev einen anderen freien Portbereich und gibt die URLs aus. Bei den Standardports ist die Anwendung unter http://127.0.0.1:5173 erreichbar. Sie sollten eine Anmeldeseite sehen.
Auf einem VPS sitzen Sie nicht direkt an diesem Rechner. Sie sollten Port 5173 nicht veröffentlichen, um die Anwendung zu erreichen. Leiten Sie die Ports stattdessen von Ihrem eigenen Rechner über SSH (Secure Shell) weiter.
ssh -L 5173:127.0.0.1:5173 -L 3100:127.0.0.1:3100 you@your-serverBeachten Sie den Unterschied zwischen den Ausführungsarten. pnpm dev führt Vite auf dem Host aus und bindet es lokal. Der Dienst web der Compose-Datei für die Entwicklung veröffentlicht 127.0.0.1:5173:5173. Sein Dienst api verwendet 127.0.0.1:3100:3100. Beide sind nur an die Loopback-Schnittstelle gebunden, daher funktioniert derselbe Tunnel auch dafür. In der Produktionsdatei veröffentlicht die Webanwendung keinen Host-Port. Sie stellt Port 5173 nur den Containern in ihren eigenen Netzwerken bereit. Nur Caddy veröffentlicht die Ports 80 und 443. Verwenden Sie daher für alles, was dauerhaft laufen soll, die Produktionsdatei mit ihrem Reverse Proxy.
Welcher Sandbox-Anbieter ist auf einem Server sicher?
Diese Einstellung muss korrekt gesetzt sein. SANDBOX_PROVIDER in .env ist standardmäßig auf docker gesetzt. Der festgelegte Checkout unterstützt außerdem Railway neben den im Self-Host-Dokument aufgeführten Anbietern.
dockerist die Standardeinstellung. Bot-Computer laufen als Container auf Ihrem Rechner. Sie werden aus dem Imagepnpm sandbox:builderstellt und unter einem Supervisor ausgeführt. Die Bots eines Workspace verwenden standardmäßig gemeinsam einen Team Computer. Nur auf einem Private Computer erhält ein Bot einen eigenen Container. Ein E2B-Konto ist nicht erforderlich.e2bführt die Bot-Computer auf E2B aus und benötigtE2B_API_KEY. Unterv0.3.5akzeptiert die Factory den Anbieter in Produktionsumgebungen, wenn der Schlüssel angegeben ist, ohne Einschränkung durchNODE_ENV. Im Self-Host-Dokument wird dieser Anbieter für öffentliche oder von mehreren Benutzern verwendete Produktionsumgebungen empfohlen. Die Bot-Computer bleiben dabei vom Host getrennt, auf dem Ihre API und Ihre Datenbank laufen.daytona,createosundboatsind weitere Remote-Anbieter. Jeder benötigt einen eigenen Schlüssel:DAYTONA_API_KEY,CREATEOS_SANDBOX_API_KEYoderBOAT_API_KEY.railwayführt Computer auf Railway aus und benötigtRAILWAY_API_TOKENsowie ein auf API und Worker explizit ausgewähltesRAILWAY_ENVIRONMENT_ID. Verwenden Sie für Sandboxes ein eigenes Railway-Projekt oder eine eigene Umgebung.desktopführt die Befehle des Bots direkt auf dem Host von API und Worker aus, wie es im Dokument beschrieben wird. Unterv0.3.5verweigern API und Worker den Start, sofernNODE_ENVnichtdevelopmentodertestist..env.examplewird jedoch mitNODE_ENV=developmentausgeliefert. Daher akzeptiert ein Server mitpnpm devdiese Einstellung weiterhin. Aktivieren Sie sie nicht auf einem öffentlichen oder gemeinsam genutzten Dienst.fakeist nur ein Emulator zur Verifikation. Es ist keine Laufzeitumgebung.nonestartet das Produkt ohne Computer-Host.
Nehmen Sie diese Beschreibung wörtlich. Im Desktop-Modus gibt es überhaupt keine Isolationsgrenze. Der Bot führt Shell-Befehle als der Benutzer aus, unter dem der API-Prozess läuft. Er hat Zugriff auf dessen Home-Verzeichnis, dessen SSH-Schlüssel, dessen Cloud-Anmeldedaten und dessen .env. Text auf einer vom Bot gelesenen Webseite wird dadurch zu einem Befehl auf Ihrem Server. Im Desktop-Modus kann ein Bot auf einem Server Ihre Anmeldedaten übernehmen. Verwenden Sie diesen Modus nur auf einem Rechner, an dem Sie selbst arbeiten, oder überhaupt nicht. Ein Wechsel des Anbieters setzt einen Container um diesen Pfad zu Webseiten, schließt ihn aber nicht. Wenn Sie einem Bot ein eigenes SearXNG-Such-Backend geben, wird dieselbe Angriffsfläche auch auf der Suchseite abgedeckt.
docker bildet eine echte Grenze zwischen den Bots und Ihrem Host. Zwischen den Bots ist diese Grenze jedoch schwach. Standardmäßig verwenden sie gemeinsam einen Team Computer. Im Dokument zur Computer-Laufzeit steht, dass Team-Bots den Betriebssystembenutzer, den Workspace, Browserprofile sowie den Shell- und X11-Zugriff gemeinsam nutzen. Die botbezogenen Verzeichnisse organisieren die Arbeit, sind aber keine Sicherheitsgrenzen. Daher kann jeder Team-Bot die Dateien anderer Team-Bots lesen. Ein Bot, der eigene Grenzen benötigt, gehört auf einen Private Computer. Der Docker-Anbieter führt diesen als separaten Schwestercontainer in einem eigenen Netzwerk aus. Der Supervisor, der diese Container erstellt, bindet jedoch /var/run/docker.sock ein. Im Self-Host-Dokument wird dies ausdrücklich erklärt: Der Zugriff auf diesen Socket entspricht der vollständigen Kontrolle über den Docker-Host. Halten Sie den Supervisor daher privat. .env.example behandelt SANDBOX_SUPERVISOR_TOKEN als eigenes Anmeldedatum, getrennt von BETTER_AUTH_SECRET. Docker-Sandboxes benötigen es außerhalb der lokalen Entwicklung. Das Produkt wird mit einem Platzhalter ausgeliefert, den jeder auf GitHub lesen kann. Vergeben Sie dafür einen eigenen zufälligen Wert. Für die stärkste hier verfügbare Trennung verwenden Sie e2b oder geben Sie Rakazo einen Rechner, auf dem sich nichts anderes befindet. Das ist derselbe Grundgedanke wie beim Ausführen von Coding-Agents in einer kurzlebigen VM: Am günstigsten übersteht ein Agent einen Fehler, wenn sein Rechner keinen Wert hat.
Wo werden Modell-API-Schlüssel abgelegt?
Die optionale Abrechnung von Modellguthaben in Rakazo bleibt deaktiviert, solange nicht beide Stripe-Schlüssel gesetzt sind. Sie bringen den Schlüssel selbst mit. .env.example setzt PI_DEFAULT_PROVIDER=openrouter. Deshalb ist OPENROUTER_API_KEY normalerweise der richtige Ort, und Provider-Schlüssel funktionieren über dieselbe Einstellung.
Bewahren Sie den Schlüssel in .env auf und nehmen Sie ihn nicht in eine Datei auf, die Sie committen. Beide Compose-Befehle im Repository übergeben --env-file .env. Dadurch gelangen die Werte in die Container, ohne jemals in von git erfasste YAML-Dateien geschrieben zu werden. Sie können OPENROUTER_API_KEY auch leer lassen und nach der Registrierung in der Anwendung ein Modell verbinden. Das ist ein weiterer Grund dafür, dass ENCRYPTION_KEY einen echten zufälligen Wert statt des mitgelieferten Platzhalters benötigt.
Legen Sie beim Provider ein Ausgabenlimit für den Schlüssel fest, bevor ein Bot ihn verwendet. Ein Bot, der in einer Schleife läuft, verursacht Ausgaben. Rakazo stellt außerdem MAX_TOOL_CALLS_PER_TURN bereit: Setzen Sie dort eine positive Ganzzahl, um einen Durchlauf, der sein Budget für Tool-Aufrufe überschreitet, kontrolliert zu beenden und trotzdem eine abschließende Nachricht des Assistenten zu erzeugen. Wenn 0 nicht gesetzt oder leer ist, bleibt das Limit unbegrenzt. Gezählt werden Tool-Aufrufe, nicht Geldbeträge. Diese Einstellung ersetzt daher nicht das Ausgabenlimit des Providers. Verwenden Sie für diesen Schlüssel einen eigenen Namen, damit Sie ihn separat widerrufen können. Wenn Sie dies für ein Team statt für sich selbst einrichten, ist OneCLI als zentrales Gateway vor den Agents aller Benutzer eine andere Lösung für dasselbe Problem, weil die Provider-Schlüssel an einer Stelle statt für jede Person einzeln verwaltet werden.
Vom Entwicklungsmodus zu einem Setup, das dauerhaft laufen kann
Das Repository enthält eine Compose-Datei für den Produktivbetrieb. Sie startet Postgres, die API, den Worker, die Webanwendung und Caddy für TLS-Zertifikate (Transport Layer Security), die Caddy automatisch anfordert. Nur Caddy veröffentlicht darin Ports. Standardmäßig verwendet die Konfiguration E2B für die Bot-Computer. Ein optionales Overlay, infra/compose/docker-compose.prod.docker.yml, verwendet stattdessen lokale Docker-Computer im selben Stack. Die Dokumentation weist darauf hin, dass der hinzugefügte Supervisor auf dem Host über Root-Rechte verfügt.
sudo --preserve-env=SSH_CONNECTION DEPLOY_USER=deploy bash infra/compose/harden-host.sh
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
build --build-arg GIT_SHA=$(git rev-parse HEAD)
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
up -d --wait --pull never
curl --fail https://app.example.com/healthErstellen Sie ein Konto deploy, das ausschließlich die Anmeldung per Schlüssel erlaubt. Bestätigen Sie, dass Sie sich damit anmelden können, bevor Sie das Skript ausführen. harden-host.sh deaktiviert SSH-Passwörter und die Root-Anmeldung, begrenzt SSH-Verbindungen, erlaubt SSH, HTTP und HTTPS über UFW (Uncomplicated Firewall) und erhält vorhandene Regeln für private Netzwerke. Außerdem aktiviert es fail2ban, unbeaufsichtigte Sicherheitsupdates, AppArmor und Audit-Regeln. Ohne SSH_CONNECTION wird die Ausführung verweigert. Deshalb übergibt der Befehl diesen Wert über sudo. Die Firewall-Änderung wird zurückgesetzt, sofern Sie sie nicht innerhalb von drei Minuten aus einer neuen SSH-Sitzung bestätigen. Lesen Sie das Skript, bevor Sie es ausführen. Es ändert Ihre Anmeldemethode und lädt SSH neu. Lassen Sie die Konsole Ihres Providers geöffnet, bis eine neue SSH-Anmeldung erfolgreich ist.
Die Produktionskonfiguration .env benötigt mehr als die Entwicklungsumgebung. Die Dokumentation zum Self-Hosting nennt diese Mindestanforderungen sowie die Secrets.
NODE_ENV=production
RAKAZO_HOST=app.example.com
BETTER_AUTH_URL=https://app.example.com
WEB_ORIGIN=https://app.example.com
API_URL=https://app.example.com
SIGNUPS_ENABLED=true
SIGNUP_ALLOWLIST=you@example.com
SANDBOX_PROVIDER=e2b
AGENT_RUNTIME=pi
WAKEUP_DRIVER=graphile
DATA_DIR=/data
RAKAZO_DEPLOY_DIR=/srv/rakazo
RAKAZO_IMAGE_TAG=local
POSTGRES_PASSWORD=<random, URL-safe>
POSTGRES_APP_PASSWORD=<random, URL-safe>
BETTER_AUTH_SECRET=<random>
ENCRYPTION_KEY=<64 random hex characters>
SCREEN_PROXY_SECRET=<random>
E2B_API_KEY=<your key>
OPENROUTER_API_KEY=<your key>Verweisen Sie vor dem ersten up einen A-Record auf den Server. Caddy fordert für den in RAKAZO_HOST angegebenen Namen ein Zertifikat an. Der Name muss auf diesen Server aufgelöst werden. Außerdem muss entweder Port 80 für die HTTP-Validierung oder Port 443 für die TLS-ALPN-Validierung von außen erreichbar sein. Beide Verfahren sind standardmäßig aktiviert. Das Schließen von Port 80 verhindert daher die Zertifikatsausstellung über Port 443 nicht.
Lassen Sie SIGNUP_ALLOWLIST von Anfang an auf Ihre eigene Adresse gesetzt. .env.example enthält SIGNUPS_ENABLED=true. Beide Einstellungen werden bei jedem Start der API aus der Umgebung gelesen. Eine Instanz unter einem öffentlichen Namen mit aktivierten Registrierungen und ohne Allowlist akzeptiert daher Registrierungen von jeder Person, die sie findet. Eine nicht leere Allowlist wird bei jedem Start angewendet und ersetzt die gespeicherte Liste. Für eine Registrierung über die Allowlist ist eine Bestätigung des E-Mail-Postfachs erforderlich. Das gilt auch für das erste Konto. Richten Sie deshalb die E-Mail-Zustellung ein, bevor Sie sich registrieren. Ohne E-Mail sieht die Dokumentation vor, zunächst mit SIGNUPS_ENABLED=false zu starten und das Konto mit dem dort beschriebenen serverseitigen Bootstrap-Befehl zu erstellen. Dadurch entsteht ein gewöhnliches verifiziertes Konto ohne Serverrechte. Setzen Sie zuerst die Allowlist. Sie können sie später lockern. Wenn Sie bereits mehrere Dienste auf demselben Server betreiben und lieber eine gemeinsame Personenliste statt einer Allowlist pro Anwendung verwenden möchten, setzen Sie eine Authentik-Instanz davor. Dadurch wird diese Entscheidung an den Proxy verlagert. Authentik steht dabei vor den eigenen Better-Auth-Konten von Rakazo und ersetzt sie nicht.
Behandeln Sie docs/self-host.md im Repository als maßgebliche Quelle für die Produktionseinstellungen. Diese Datei ändert sich zusammen mit dem Code, während diese Anleitung nicht automatisch angepasst wird. Da Compose die Arbeit übernimmt, gelten die üblichen Regeln. Die Grundlagen von Docker Compose für einen VPS erklären, warum --env-file und benannte Volumes wichtiger werden, sobald ein Stack monatelang unbeaufsichtigt laufen soll.
Backups
Postgres und das Verzeichnis data/ enthalten in diesem Setup die Daten der Instanz. Für die Wiederherstellung werden außerdem ENCRYPTION_KEY und alle konfigurierten Content-Master-Keys benötigt. Bewahren Sie Kopien außerhalb des Servers auf.
./scripts/backup.sh
./scripts/restore.sh backups/BACKUP_TIMESTAMPbackup.sh erstellt einen Dump von Postgres und archiviert data/. restore.sh funktioniert im Compose-Stack für die Entwicklung. Führen Sie es in einer leeren Datenbank aus, während die Anwendungsdienste beendet sind. Das Tool liest die Produktions-Backup-Dateien nicht. Installieren Sie infra/compose/backup-prod.sh auf einem Server, von dem Sie abhängig sind, als /usr/local/sbin/rakazo-backup zusammen mit dem vom Repository bereitgestellten Timer. Das Tool schreibt einen verifizierten Dump und ein Archiv der Anwendungsdaten nach /var/backups/rakazo. Standardmäßig werden bis zu drei verifizierte Snapshots aufbewahrt. Die Anzahl wird durch RAKAZO_BACKUP_KEEP festgelegt. Die Snapshots bleiben innerhalb einer durch RAKAZO_BACKUP_MAX_GB festgelegten Grenze von 50 GiB. Vor jedem Lauf werden unvollständige Snapshots und überzählige alte Snapshots gelöscht. Die Rotation erfolgt daher automatisch. Sie können jedes Backup außerdem mit age für die öffentlichen Empfänger verschlüsseln, die Sie in /etc/rakazo/backup.env angeben. Dadurch schreibt der Server Backups, die er selbst nicht lesen kann. Erzeugen Sie dieses Schlüsselpaar auf einem von Ihnen kontrollierten Rechner. Bewahren Sie den privaten Schlüssel außerhalb des Servers auf. Ohne Empfänger bleibt das Backup unverschlüsselt, und es wird eine Warnung protokolliert. Nach dem ersten verschlüsselten Backup schlägt ein Lauf ohne Empfänger jedoch fehl, sofern Sie unverschlüsselte Backups nicht ausdrücklich mit RAKAZO_BACKUP_ALLOW_PLAINTEXT=1 erlauben. Ein Backup auf derselben Festplatte wie die Datenbank ist kein Backup. Kopieren Sie es daher vom Server weg. Stellen Sie es anschließend einmal auf einem Ersatzserver wieder her, bevor Sie es benötigen.
Warum der Fehler auftritt und was Sie sehen
pnpm db:migrate kann die Datenbank nicht erreichen. Die Migration meldet, dass sie den Datenbankserver unter 127.0.0.1:5433 nicht erreichen kann. Entweder läuft der Postgres-Container nicht, er läuft und ist noch nicht bereit, oder er wurde ohne das Overlay docker-compose.postgres-host.yml gestartet, das Port 5433 auf dem Host veröffentlicht. Führen Sie docker compose --env-file .env -f infra/compose/docker-compose.yml ps aus und prüfen Sie, ob der Postgres-Dienst den Status healthy meldet. Die Compose-Datei führt alle drei Sekunden eine Health-Prüfung aus. Wenn der Container in einer Neustartschleife hängt, lesen Sie seine Logs: Der festgelegte Compose-Stack startet auf einem alten Postgres-16-Volume erst, wenn dieses auf Postgres 18 migriert wurde. docker compose ... down -v entfernt das Volume. Dabei werden auch die Daten gelöscht.
Der Port ist bereits belegt. Das Starten von Postgres schlägt mit bind: address already in use fehl, wenn ein anderer Prozess Port 5433 verwendet. Meist handelt es sich um einen älteren Rakazo-Stack, den Sie nicht beendet haben. sudo ss -lntp | grep 5433 zeigt den Prozess an. Das Overlay liest den Host-Port aus POSTGRES_HOST_PORT. Sie können ihn daher ändern, solange Sie auch DATABASE_URL und DATABASE_MIGRATION_URL entsprechend ändern.
Ein Bot erhält nie einen Computer. Mit SANDBOX_PROVIDER=docker und ohne das Image rakazo/computer:local gibt es nichts zu starten. docker image ls rakazo/computer beantwortet diese Frage in einer Zeile, und pnpm sandbox:build behebt das Problem. Wenn der Supervisor den Docker-Socket nicht erreichen kann, kann er ebenfalls keine Container erstellen. Die Meldung nennt den Pfad: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock.
Ein langer Befehl bricht unterwegs ab. .env.example setzt SANDBOX_COMMAND_TIMEOUT_MS=300000. Dadurch wird ein einzelner Befehl im Computer eines Bots nach fünf Minuten beendet. Erhöhen Sie diesen Wert für langsame Builds, statt von einem Absturz der Sandbox auszugehen.
pnpm install funktioniert auf verwirrende Weise nicht. Prüfen Sie zuerst node -v. Der Workspace deklariert ^22.22.2 || ^24.0.0 || >=26.0.0. Daher liegen 23.x, 25.x und alle 22.x-Versionen vor 22.22.2 außerhalb dieses Bereichs. Das festgelegte .npmrc setzt engine-strict=true. Daher weist pnpm install eine nicht unterstützte Node-Version mit einem Engine-/Versionsfehler zurück, bevor der Code der Anwendungsabhängigkeiten ausgeführt wird.
Die Anmeldung funktioniert lokal, aber nicht über die Domain. BETTER_AUTH_URL, WEB_ORIGIN und API_URL müssen alle dieselbe öffentliche Origin wie die Adressleiste enthalten, einschließlich des Schemas. Ein veralteter Wert in http://127.0.0.1:5173 ist normalerweise die Ursache dafür, dass eine Sitzung nicht bestehen bleibt.
Aktualisieren eines angepinnten Checkouts
Der Upgrade-Pfad in der Self-Hosting-Dokumentation für einen produktiven Compose-Stack aus Ihrem Checkout ist kurz: Rufen Sie den neuen Quellcode ab und erstellen Sie anschließend die Images für die API, den Worker und die Webanwendung neu. Starten Sie diese Dienste danach neu. Migrationen werden beim Start der API ausgeführt, weil der Startbefehl sie anwendet, bevor die API Anfragen verarbeitet.
sudo /usr/local/sbin/rakazo-backup
git fetch --all --tags
git checkout NEW_COMMIT_SHA
export GIT_SHA=$(git rev-parse HEAD)
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
up -d --wait --pull never --build api worker webErstellen Sie zuerst ein Backup. Migrationen lassen sich nur vorwärts ausführen, und bei einer Beta gibt es keinen verlässlichen Rückweg. Wenn Ihr Checkout älter als 30 August 2026 ist, was den Commit v0.1.0-beta einschließt, lesen Sie vor dem Upgrade den Hinweis der Dokumentation zur Migration 20260830200000_space_scope_names_and_user_credentials. Dabei handelt es sich um eine koordinierte Umstellung. Stoppen Sie daher zuerst die alte API und den alten Worker und führen Sie die in der Dokumentation beschriebene Prüfung der Space-Privacy-Grenze aus. Wenn Sie von einem Checkout aktualisieren, der vor der Einführung des separaten App-Logins erstellt wurde, setzen Sie POSTGRES_APP_PASSWORD in .env, bevor Sie die Images neu erstellen. Die produktive Compose-Datei startet sonst nicht. Die Compose-Dateien für den Source-Checkout und für die Produktion verwenden außerdem Postgres 18. Eine vorhandene Postgres-16-Installation benötigt das in der Dokumentation beschriebene Verfahren infra/compose/upgrade-postgres.sh, bevor sie mit dem neuen Layout starten kann. Lesen Sie die Commits zwischen Ihrer angepinnten SHA und der neuen SHA, bevor Sie sie übernehmen. Ein so junges Projekt benennt Umgebungsvariablen gelegentlich ohne Ankündigung um. Eine fehlende Variable zeigt sich dann als Dienst, der startet und anschließend beendet wird. Wenn Sie noch entscheiden, ob Rakazo überhaupt das Richtige für Sie ist, behandelt die Übersicht zu selbst gehosteten KI-Agenten, welche weiteren Projekte in diese Kategorie fallen und welche Kosten für ihren dauerhaften Betrieb entstehen.
FAQ
Kann ich Rakazo auf einem 1-GB-VPS ausführen?
Nein. Postgres, die API, der Worker, der Sandbox-Supervisor und die Webanwendung laufen gleichzeitig. Mit SANDBOX_PROVIDER=docker fügt der Computer der Bots außerdem einen Container mit einer grafischen Desktop-Umgebung hinzu. Für jeden aktiven Bot laufen darin ein eigener X-Display- und Chrome-Prozess. Insgesamt gilt standardmäßig eine Obergrenze von 2 GB Arbeitsspeicher und zwei CPUs. Die Self-Hosting-Dokumentation unter v0.3.5 nennt keine Host-Größe. Rechnen Sie für die Steuerungsebene mit 4 GB als Untergrenze. Wenn die Desktops auf Ihrem Rechner ausgeführt werden, sollten Sie mehr einplanen.
Ist der Desktop-Sandbox-Provider auf einem Server sicher?
Nein. In der Self-Hosting-Dokumentation steht, dass desktop Befehle direkt auf dem Host der API und des Workers ausführt. Der Bot handelt dadurch mit dem Benutzerkonto, unter dem der Prozess läuft, und kann auf dessen Dateien und Zugangsdaten zugreifen. Unter v0.3.5 verweigern API und Worker die Verwendung außerhalb des Entwicklungs- und Testmodus. Ein Server mit pnpm dev läuft jedoch im Entwicklungsmodus und akzeptiert sie. Verwenden Sie diese Konfiguration nicht auf einem öffentlichen oder gemeinsam genutzten Server. Verwenden Sie docker, wenn ein Bot einen Private Computer erhalten muss und keine Dateien mit den anderen Bots des Workspace teilen darf. Verwenden Sie e2b, wenn sich mehr als eine Person anmeldet.
Welche Version von Rakazo soll ich installieren?
Stand 9 November 2026 ist v0.8.0 das neueste Release. Es wurde am 4 November 2026 veröffentlicht und als Latest gekennzeichnet. Um dieser Anleitung zu folgen, wechseln Sie zum festgelegten Commit v0.3.5, f31e3c0699f086d663637c4107858c238a086fb3. Folgen Sie nicht main und verwenden Sie nicht das August-v0.1.0-beta-Prerelease. Ein Branch ändert sich unter Umständen, und ein Tag kann auf einen anderen Commit gesetzt werden. Daher identifiziert keiner von beiden einen Tree, zu dem Sie zurückkehren können. Notieren Sie den Commit. Ein Rollback ist nur möglich, wenn Sie wissen, welcher Commit funktioniert hat.
Wo hinterlege ich meinen OpenRouter-API-Key?
In .env als OPENROUTER_API_KEY. Hinterlegen Sie ihn niemals in einer Compose-Datei, die Sie committen. Beide Compose-Befehle im Repository übergeben --env-file .env. Der Wert gelangt dadurch in die Container, ohne in versioniertem YAML gespeichert zu werden. Sie können das Feld auch leer lassen und nach der Registrierung in der Anwendung ein Modell verbinden. Legen Sie beim Provider ein Ausgabenlimit für den Key fest. Ein Bot in einer Endlosschleife ruft das Modell weiter auf, bis etwas ihn stoppt.
Benötige ich einen Domainnamen und TLS?
Für alles, was über einen ersten Test hinausgeht, ja. Die Produktions-Compose-Datei führt Caddy aus und bezieht Zertifikate automatisch. Setzen Sie RAKAZO_HOST auf den öffentlichen Hostnamen. Setzen Sie BETTER_AUTH_URL, WEB_ORIGIN und API_URL auf denselben öffentlichen HTTPS-Ursprung. Für einen ersten Test können Sie die Domain weglassen. Führen Sie pnpm dev aus und leiten Sie Port 5173 über SSH weiter, statt ihn zu veröffentlichen.