Rakazo zelf hosten op een VPS: handleiding en installatie

Wat zelf-hosting van Rakazo daadwerkelijk inhoudt

Zelf-hosting van Rakazo betekent dat u vijf onderdelen op één Linux-server draait: PostgreSQL, een Graphile Worker-proces, de API, de webapplicatie en één sandbox-container voor elke actieve bot. Rakazo is een open-source alternatief voor Grok Bot, gepubliceerd door elie222 onder de Apache 2.0-licentie. Elke bot krijgt een eigen thread, een eigen computer, eigen geheugen en een eigen geschiedenis, en kan peers of kortstondige subagents aanmaken.

Dat laatste is de reden waarom dit op een VPS (virtual private server) thuishoort en niet op een desktop. Een bot die geheugen vasthoudt en geplande taken uitvoert, moet bereikbaar zijn terwijl u slaapt. Een laptop die in de slaapstand gaat, verbreekt de wachtrij.

Rakazo bevindt zich in augustus 2026 in een vroege bètafase; beschouw dit dus als een werkende opstelling en niet als een kant-en-klaar product. De stack is volledig TypeScript: React 19 en Vite voor de webapplicatie, Hono voor de API, Postgres met Prisma, Better Auth voor accounts en Graphile Worker voor achtergrondtaken. Graphile Worker slaat de wachtrij op in Postgres, waardoor er geen Redis of tweede datastore nodig is. .env.example stelt WAKEUP_DRIVER=graphile in, wat betekent dat het ontwaken van een bot een Postgres-gebaseerde taak is. Stop Postgres en elke geplande bot-actie stopt daarmee. Als u liever zelf een agent samenstelt uit onderdelen in plaats van het product van iemand anders te draaien, is het bouwen van uw eigen agent uit componenten de andere route.

Waarom een 1 GB-abonnement hiervoor niet volstaat

Tel de processen. Postgres is er één. De API is een Node-proces. De worker is een tweede. De web-app is een derde. De sandbox-supervisor is een vierde. Vervolgens krijgt elke actieve bot een container met een grafische Linux-desktop en een browser.

De eigen self-host-documentatie van het project noemt één eerlijk cijfer: een machine met 2 vCPU's en 4 GB RAM is voldoende voor de API, de worker en Postgres wanneer E2B de bot-desktops beheert. Dat is het getal voor enkel het control plane, waarbij het zware werk elders wordt gehost. Configureer SANDBOX_PROVIDER=docker en die desktops verhuizen naar uw VPS, waardoor 4 GB de ondergrens wordt in plaats van het streefdoel. Begin bij 8 GB als u van plan bent om meer dan één bot actief te houden, en meet het werkelijke verbruik met docker stats terwijl een bot aan het werk is. De browser in de sandbox is wat het geheugengebruik doet stijgen, dus een specificatielijst zal u dat niet vertellen. Voor de algemene methode om een server voor agent-werk te dimensioneren, behandelt hoeveel RAM en CPU een agent-VPS daadwerkelijk nodig heeft de meting in detail.

Eén instelling voorkomt dat dit erger wordt. .env.example wordt geleverd met SANDBOX_IDLE_MS=600000, inclusief de opmerking dat dit E2B-computers pauzeert, of Docker-containers stopt, na dat aantal milliseconden inactiviteit. Na tien minuten inactiviteit wordt de computer verwijderd. De minimaal geaccepteerde waarde is 30000. Zonder dit zou elke bot die u ooit hebt geopend, voor altijd geheugen in beslag nemen.

Schijfruimte telt ook mee. De sandbox-image, de Node-modules en het Postgres-volume delen één schijf, dus 40 GB is een verstandig startpunt.

Pin een versie voordat u kloont

Rakazo ontwikkelt zich snel en main is geen release. Sinds 16 augustus 2026 bevat de repository precies één tag, v0.1.0-beta, gepubliceerd op 13 augustus 2026 en gemarkeerd als een prerelease.

git clone https://github.com/elie222/rakazo.git
cd rakazo
git checkout 53b119a68d9ef843d23aa3b7e3719b6be7b51fdb
git log -1 --format='%H %ci'

Die commit is degene waar v0.1.0-beta naar verwijst. Pin de commit in plaats van de branch of de tag. Een branch verandert onder uw voeten bij de volgende git pull, en een tag is een verplaatsbaar label dat een beheerder kan aanpassen, dus geen van beide identificeert een boomstructuur waar u naar terug kunt keren. Een commit-identifier kan niet bewegen. Noteer de uwe naast uw andere servergegevens, want wanneer een upgrade voor problemen zorgt, is de goedkope oplossing git checkout <old commit> en een herbouw, en dat werkt alleen als u weet welke commit werkte.

Vereisten: Node 22, pnpm 9 en Docker

node -v
pnpm -v
docker --version

package.json declareert "engines": { "node": ">=22" } en "packageManager": "pnpm@9.15.0", dus node -v moet v22 of hoger weergeven. Het Node-pakket in het Ubuntu-archief is doorgaans ouder dan dat; installeer daarom vanuit NodeSource of via nvm. pnpm wordt samen met Node geleverd via corepack:

corepack enable
corepack prepare pnpm@9.15.0 --activate

Docker Engine inclusief de compose-plugin dekt de rest, en uw gebruiker moet de daemon kunnen bereiken. Als docker ps het antwoord permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock geeft, voeg uw gebruiker dan toe aan de docker-groep en open een nieuwe login-shell. Wees u bewust van de implicaties: lidmaatschap van docker staat gelijk aan root-toegang op de machine, omdat iedereen in die groep een container kan starten die het bestandssysteem van de host mount.

Configureer .env en start Postgres

cp .env.example .env
chmod 600 .env

Twee waarden moeten worden gewijzigd voordat er verbinding met een netwerk wordt gemaakt. .env.example levert BETTER_AUTH_SECRET=replace-with-32-plus-character-secret en ENCRYPTION_KEY=replace-with-64-char-hex-or-passphrase. Rakazo weigert deze placeholder-waarden buiten een ontwikkelomgeving; een onvolledig geconfigureerde implementatie faalt daarom direct in plaats van te draaien met een geheim dat in de repository is gepubliceerd.

openssl rand -base64 48
openssl rand -hex 32

Start vervolgens de database afzonderlijk en voer de migraties uit.

docker compose --env-file .env -f infra/compose/docker-compose.yml up postgres -d
pnpm install
pnpm db:generate
pnpm db:migrate
pnpm sandbox:build

pnpm sandbox:build bouwt de image voor de bot-computer, gedefinieerd in package.json als docker build -t rakazo/computer:local infra/sandboxes/computer. Dit is een grafische image, waardoor de eerste build veel data ophaalt en tijd in beslag neemt. Controleer of de image is geland met docker image ls rakazo/computer; dit commando hoort één rij weer te geven.

Het compose-bestand publiceert Postgres als 127.0.0.1:5433:5432, wat alleen via loopback bereikbaar is. Laat dit zo. De ontwikkelingsreferenties zijn rakazo:rakazo; deze staan in de repository en een Postgres-poort die vanaf het internet bereikbaar is met een gepubliceerd wachtwoord wordt binnen enkele uren door scanners gevonden. Het productie-compose-bestand leest in plaats daarvan POSTGRES_PASSWORD, dus stel dit in op een willekeurige reeks tekens zodra u zover bent.

De eerste uitvoering

pnpm dev

Dit start vier onderdelen: de API op poort 3100, de Graphile Worker, de Vite web-app op 5173 en de sandbox-supervisor op 7091. De app bevindt zich op http://127.0.0.1:5173 en u zou een inlogpagina moeten zien.

Op een VPS zit u niet fysiek bij de machine en u moet poort 5173 niet openstellen om deze te bereiken. Forward de poorten in plaats daarvan via SSH (secure shell) vanaf uw eigen machine.

ssh -L 5173:127.0.0.1:5173 -L 3100:127.0.0.1:3100 you@your-server

Wees voorzichtig met het verschil tussen de twee manieren om dit uit te voeren. pnpm dev draait Vite op de host, gebonden aan localhost. De web-service in het compose-bestand publiceert 5173:5173 op elke interface. Start de volledige development compose-stack op een publieke VPS en de app is direct toegankelijk; gebruik daarom het productiebestand en de bijbehorende reverse proxy voor alles wat u actief laat draaien.

Welke sandbox-provider is veilig op een server?

Dit is de instelling die u correct moet configureren. SANDBOX_PROVIDER in .env accepteert vier waarden.

• docker is de standaardinstelling. Elke bot krijgt een eigen container op uw machine, gebouwd op basis van de image die pnpm sandbox:build heeft geproduceerd. Dit is de snelste zelf-gehoste configuratie.
• e2b voert de bot-computers uit op E2B en vereist E2B_API_KEY. Het project raadt dit aan voor publieke of multi-user implementaties, omdat het de bot-computers gescheiden houdt van de host waarop uw API en database draaien.
• desktop voert de commando's van de bot direct uit op de API- en worker-host. De instructie in de repository is duidelijk: gebruik dit niet op een publieke of gedeelde server.
• fake is een in-process emulator voor tests. Het is geen runtime.

Neem die waarschuwing voor desktopmodus letterlijk. In desktopmodus is er geen enkele isolatiegrens; de bot voert shell-commando's uit als de gebruiker die het API-proces draait, met de home-directory van die gebruiker, de SSH-sleutels van die gebruiker, de cloud-inloggegevens van die gebruiker en de .env van die gebruiker. Tekst op een webpagina die de bot leest, wordt een commando op uw server. Desktopmodus op een server is de manier waarop een bot uiteindelijk uw inloggegevens in handen krijgt. Gebruik het alleen op een machine waar u zelf achter zit, of gebruik het helemaal niet.

docker vormt een echte grens, maar wel een imperfecte. De ene bot kan de bestanden van de andere bot niet lezen, omdat elke bot een eigen container heeft. De supervisor die deze containers aanmaakt, mount echter /var/run/docker.sock, en controle over de Docker-socket van de host betekent controle over de host zelf. Houd de supervisor daarom privé. .env.example documenteert SANDBOX_SUPERVISOR_TOKEN als een optionele, afzonderlijke service-credential die standaard BETTER_AUTH_SECRET is wanneer deze leeg is. Dit betekent dat het ongewijzigd laten van dat geheim de container-aanmakende service beschermt met een tekenreeks die iedereen op GitHub kan lezen. Stel beide waarden in. Gebruik voor de sterkst mogelijke scheiding e2b, of geef Rakazo een machine waar verder niets op staat. Dat is dezelfde redenering als achter het draaien van coding agents in een wegwerpbare VM: de goedkoopste manier om te overleven als een agent een fout maakt, is door te zorgen dat de machine waarop hij draait geen waarde heeft.

Waar moeten model-API-keys worden geplaatst?

Rakazo heeft geen beheerde facturering voor modellen. U dient zelf de key aan te leveren. .env.example stelt PI_DEFAULT_PROVIDER=openrouter in, dus OPENROUTER_API_KEY is de gebruikelijke locatie, en keys van providers werken via dezelfde instelling.

Houd de key in .env en buiten elk bestand dat u commit. Beide compose-commando's in de repository geven --env-file .env door, waardoor waarden de containers bereiken zonder ooit in YAML te worden geschreven die door git wordt bijgehouden. U kunt OPENROUTER_API_KEY ook leeg laten en tijdens de onboarding een key in de app plakken; dit is nog een reden waarom ENCRYPTION_KEY een echte willekeurige waarde nodig heeft in plaats van de meegeleverde placeholder.

Stel een bestedingslimiet in op de key bij de provider voordat een bot deze ooit gebruikt. Een bot die in een lus raakt, is een bot die kosten maakt, en een limiet per key is de enige stop die niet afhankelijk is van uw toezicht. Geef deze key een eigen naam zodat u deze afzonderlijk kunt intrekken.

Van ontwikkelmodus naar een permanente productieomgeving

De repository bevat een productie-compose-bestand dat Postgres, de API, de worker, de webapplicatie en Caddy uitvoert voor TLS-certificaten (transport layer security) die automatisch worden verkregen. Voor de bot-computers is E2B vereist.

sudo DEPLOY_USER=deploy bash infra/compose/harden-host.sh
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml up -d --build

harden-host.sh schakelt SSH-wachtwoordinlog uit, stelt UFW-regels (uncomplicated firewall) in voor SSH, HTTP en HTTPS, activeert fail2ban en past AppArmor-profielen toe. Lees het script door voordat u het uitvoert, aangezien het de manier waarop u inlogt wijzigt. Houd een tweede SSH-sessie open terwijl het script draait.

De productie-.env vereist meer dan de ontwikkelversie. De documentatie voor zelfhosting vermeldt deze minimumvereisten.

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
POSTGRES_PASSWORD=<random>
BETTER_AUTH_SECRET=<random>
ENCRYPTION_KEY=<random>
E2B_API_KEY=<your key>
OPENROUTER_API_KEY=<your key>
SANDBOX_PROVIDER=e2b
AGENT_RUNTIME=pi
DATA_DIR=/data

Wijs een A-record naar de server voordat u de eerste up uitvoert. Caddy vraagt een certificaat aan voor de naam in RAKAZO_HOST; de aanvraag mislukt als de naam niet naar deze server verwijst of als poort 80 niet openstaat voor extern verkeer.

Stel ook SIGNUP_ALLOWLIST=you@example.com in. SIGNUPS_ENABLED=true is de standaardinstelling, waardoor een instantie op een publieke domeinnaam registraties accepteert van iedereen die deze vindt, waarbij elk nieuw account een computer krijgt. Gebruik eerst een allowlist. U kunt deze later versoepelen indien gewenst.

Beschouw docs/self-host.md in de repository als de autoriteit voor productie-instellingen, aangezien dit bestand verandert met de code en deze handleiding niet. Omdat Compose het werk verricht, zijn de gebruikelijke regels van toepassing, en de basisprincipes van Docker Compose voor een VPS leggen uit waarom --env-file en named volumes belangrijker worden zodra een stack voor langere tijd onbeheerd draait.

Backups

Postgres en de map data/ vormen samen de volledige instantie.

./scripts/backup.sh
./scripts/restore.sh backups/BACKUP_TIMESTAMP

backup.sh maakt een dump van Postgres en archiveert data/. Voor een machine waar u afhankelijk van bent, installeert u infra/compose/backup-prod.sh als /usr/local/sbin/rakazo-backup met de timer die de repository meelevert, zodat rotatie automatisch plaatsvindt. Een back-up die op dezelfde schijf staat als de database is geen back-up; kopieer deze daarom naar een andere locatie. Test vervolgens de restore eenmaal op een reserve-server voordat u deze daadwerkelijk nodig heeft.

Waarom het mislukt en wat u zult zien

pnpm db:migrate kan de database niet bereiken. De migratie meldt dat de databaseserver op 127.0.0.1:5433 onbereikbaar is. Of de Postgres-container draait niet, of deze is nog niet gereed. Voer docker compose --env-file .env -f infra/compose/docker-compose.yml ps uit en controleer of de postgres-service als healthy wordt gerapporteerd, aangezien het compose-bestand een health check bevat die elke drie seconden wordt uitgevoerd. Een container die in een lus herstart, betekent meestal dat het pgdata-volume is aangemaakt met andere inloggegevens. docker compose ... down -v wist dit en verwijdert daarmee ook de data.

De poort is al in gebruik. Het opstarten van Postgres mislukt met bind: address already in use wanneer een ander proces poort 5433 bezet houdt; dit is meestal een eerdere Rakazo-stack die u bent vergeten te stoppen. sudo ss -lntp | grep 5433 toont de naam van het proces.

Een bot krijgt geen computer. Met SANDBOX_PROVIDER=docker en zonder rakazo/computer:local-image is er niets om op te starten. docker image ls rakazo/computer beantwoordt dit in één regel en pnpm sandbox:build lost het op. Als de supervisor de Docker-socket niet kan bereiken, kan deze ook geen containers aanmaken; de foutmelding vermeldt het pad: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock.

Een langdurig commando stopt voortijdig. .env.example stelt SANDBOX_COMMAND_TIMEOUT_MS=300000 in, waardoor een enkel commando binnen de computer van een bot na vijf minuten wordt afgebroken. Verhoog deze waarde voor trage builds in plaats van aan te nemen dat de sandbox is gecrasht.

pnpm install vertoont onduidelijke fouten. Controleer node -v voordat u iets anders doet. De workspace declareert >=22, en een verouderde Node-versie faalt in de afhankelijkheidscode in plaats van met een melding over versies.

Inloggen werkt lokaal, maar niet via het domein. BETTER_AUTH_URL, WEB_ORIGIN en API_URL moeten allemaal dezelfde publieke origin bevatten als de adresbalk, inclusief het schema. Een verouderde http://127.0.0.1:5173 die in een van deze is achtergebleven, is de gebruikelijke oorzaak van een sessie die niet behouden blijft.

Bijwerken van een vastgezette checkout

Het upgradepad in de documentatie voor self-hosting is kort: haal de nieuwe broncode op, voer de databasemigratie uit en herstart de API en de worker.

./scripts/backup.sh
git fetch --all
git checkout NEW_COMMIT_SHA
pnpm install
pnpm --filter @rakazo/db migrate
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml up -d --build

Maak eerst een back-up. Migraties zijn eenrichtingsverkeer en een bètaversie biedt geen betrouwbaar pad terug. Lees de commits tussen uw vastgezette SHA en de nieuwe versie voordat u deze toepast. Een project in deze vroege fase hernoemt soms omgevingsvariabelen zonder aankondiging; een ontbrekende variabele zorgt ervoor dat een service start en vervolgens direct afsluit. Als u nog twijfelt of Rakazo de juiste keuze is, behandelt het overzicht van self-hosted AI-agents welke alternatieven er in deze categorie bestaan en wat de bijbehorende beheerkosten zijn.

FAQ

Kan ik Rakazo draaien op een 1 GB VPS?

Nee. Postgres, de API, de worker, de sandbox supervisor en de web-app draaien allemaal tegelijkertijd. Bij SANDBOX_PROVIDER=docker voegt elke actieve bot een container toe die een grafische desktop en een browser bevat. De documentatie van het project zelf stelt dat 2 vCPU en 4 GB RAM alleen voldoende zijn voor de API, worker en Postgres als E2B de bot-desktops host. Beschouw 4 GB als het absolute minimum voor het control plane en kies voor meer geheugen wanneer de desktops op uw eigen machine draaien.

Is de desktop sandbox provider veilig op een server?

Nee. desktop voert de commando's van de bot direct uit op de host van de API en worker, als de gebruiker die het proces uitvoert, waardoor die gebruiker toegang heeft tot alle bestanden en inloggegevens. De repository adviseert om dit niet te gebruiken op een publieke of gedeelde server. Gebruik docker voor een container per bot, of e2b wanneer meer dan één persoon inlogt.

Welke versie van Rakazo moet ik installeren?

Sinds 16 augustus 2026 is er één tag, v0.1.0-beta, gepubliceerd op 13 augustus 2026 en gemarkeerd als prerelease. Gebruik de commit waarnaar deze verwijst, 53b119a68d9ef843d23aa3b7e3719b6be7b51fdb, in plaats van de branch main te volgen. Een branch kan wijzigen en een tag kan worden verplaatst, waardoor beide geen betrouwbare identificatie bieden van de codeversie waarnaar u wilt terugkeren. Noteer de commit-hash, aangezien terugdraaien alleen mogelijk is als u weet welke versie correct werkte.

Waar plaats ik mijn OpenRouter API-sleutel?

In .env als OPENROUTER_API_KEY, en nooit in een compose-bestand dat u commit. Beide compose-commando's in de repository geven --env-file .env door, zodat de waarde de containers bereikt zonder in de versiebeheerde YAML te worden geschreven. U kunt het veld ook leeg laten en de sleutel tijdens de onboarding in de app plakken. Stel een bestedingslimiet in bij de provider, omdat een bot in een lus het model blijft aanroepen totdat het proces wordt gestopt.

Heb ik een domeinnaam en TLS nodig?

Voor alles wat verder gaat dan een eerste test: ja. Het productie-compose-bestand voert Caddy uit en verkrijgt automatisch certificaten. RAKAZO_HOST, BETTER_AUTH_URL, WEB_ORIGIN en API_URL moeten allemaal dezelfde publieke HTTPS-oorsprong hebben. Voor een eerste kennismaking kunt u het domein overslaan: voer pnpm dev uit en forward poort 5173 via SSH in plaats van deze publiek open te stellen.