SSD Nodes Learn Hosting plans →
How to do am Matt ConnorBy Matt Connor

How to Self-Host Rakazo on Your Own VPS

Run Rakazo for your own AI bots with Node 22, pnpm, Postgres and Graphile Worker in Docker Compose. See sandbox choices, key handling, and VPS sizing.

Wetín self-hosting Rakazo dey actually run

Self-hosting Rakazo mean say you dey run five things for one Linux server: PostgreSQL, one Graphile Worker process, the API, the web app, and one sandbox container wey dey serve as the bots' computer. Rakazo na open-source alternative to Grok Bot, wey elie222 publish under Apache 2.0 licence. Each bot get im own conversations, memory, routines, and history. E share one Team Computer with other bots for the workspace unless you give am Private Computer. E fit also spawn peers or short-lived subagents. If words like memory, subagent, and tool call no clear for that sentence, this staged path through how agents actually work fit worth your afternoon first, because most settings below only make sense after you fit picture wetin bot dey do when e wake up.

Na that last part make VPS (virtual private server) better place for this thing than desktop. Bot wey dey hold memory and run scheduled work must remain reachable while you dey sleep. Laptop wey suspend go drop the queue.

Rakazo still describe itself as beta as of October 2026, even though e don start publish stable-numbered releases, so treat this as working setup, no be finished appliance. The stack use TypeScript throughout: React 19 and Vite for the web app, Hono for the API, Postgres with Prisma, Better Auth for accounts, and Graphile Worker for background jobs. Graphile Worker store im queue inside Postgres, so Redis no dey and you no need run second data store. .env.example set WAKEUP_DRIVER=graphile, meaning say when bot wake up, na Postgres-backed job dey run. If you stop Postgres, every scheduled bot action go stop too. If you prefer assemble agent from different parts instead of running another person product, building your own agent from components na the other route.

Why 1 GB plan no go hold this

Count the processes. Postgres na one. API na Node process. Worker na second one. Web app na third one. Sandbox supervisor na fourth one. Then bots' computer come: by default, na one shared Team Computer container wey hold graphical Linux desktop, with separate X display and Chrome process for every bot wey dey active.

The project's self-host doc no longer give host size. The doc for v0.3.5, wey dem check on 27 October 2026, list software requirements only. Wetin e give na per-computer ceiling: with Docker sandboxes, RAKAZO_COMPUTER_MEMORY dey default to 2g and RAKAZO_COMPUTER_CPUS to 2. This ceiling apply to each computer, no be each bot. Each workspace get one Team Computer by default, and every active Team bot dey run its desktop and browser inside am, so all of dem share those 2 GB and two cores. Na only bot wey dem move go Private Computer get container, and ceiling, wey belong to am. Set SANDBOX_PROVIDER=docker and those desktops go move onto your VPS, on top of the control plane, so 4 GB na floor, no be target. Start with 8 GB if you plan keep more than one bot awake, raise RAKAZO_COMPUTER_MEMORY so the shared computer fit actually use that memory, and measure the real number with docker stats while the bots dey work. Na the browser inside the sandbox dey move the memory line, so spec sheet no go tell you. To stop small box from running too many browsers at once, set positive SANDBOX_TEAM_SCREEN_LIMIT, wey cap active desktops for Docker Team Computer. The shipped 0 leave am uncapped. If memory tight overall, RAKAZO_COMPUTER_MEMORY also accept smaller value like 1536m. For the general method to size box for agent work, how much RAM and CPU agent VPS really need go through the measurement in detail.

One setting dey stop this from getting worse. .env.example ship with SANDBOX_IDLE_MS=600000, and the comment talk say computers dey pause or stop after that number of idle milliseconds. Ten minutes idle and the computer go disappear. The minimum accepted value na 30000, and 0 disable idle sleep. The same comment suggest 0 for Docker self-hosts, where idle computer no cost anything, so long-running apps and sessions stay up. That one apply to money, no be memory. For small VPS, leave the timer on, because without am every computer wey you ever start, and every browser inside am, go keep running.

Disk count too. Sandbox image, Node modules and Postgres volume share one disk, so 40 GB na sensible starting point.

Pin one version before you clone

Rakazo dey move fast and main no be release. As of 9 November 2026, v0.8.0, wey dem publish on 4 November 2026, na the release wey dem mark Latest. This guide still dey pinned to v0.3.5, wey dem publish on 25 October 2026.

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

Na that commit v0.3.5 dey point to. Pin the commit instead of the branch or tag. Branch fit change under you for the next git pull, and tag na movable label wey maintainer fit point somewhere else, so none of dem identify tree wey you fit return to. Commit identifier no fit move. Write your own down beside your other server facts, because when upgrade cause problem, the quick fix na git checkout <old commit> and rebuild, and this one only work if you know which commit dey work. The pinned README call Rakazo beta, so e make sense to pin am precisely with this small effort. Project wey get long history of deliberate releases fit use published tag instead, like smaller self-hosted stack like openGym.

Requirements: Node 22, pnpm 9, and Docker

node -v
pnpm -v
docker --version

package.json dey declare "engines": { "node": "^22.22.2 || ^24.0.0 || >=26.0.0" } and "packageManager": "pnpm@9.15.0". So node -v must print v22.22.2 or any later 22.x, any v24, or v26 and above. Any v22 wey older pass 22.22.2 no dey inside that range, and the README talk am clearly say Node.js 23.x and 25.x no dey supported. Install supported Node version from NodeSource or nvm. Corepack dey come with Node 22 and 24; for Node 26 and above, install am first with npm install -g corepack. Then activate pnpm:

corepack enable
corepack prepare pnpm@9.15.0 --activate

Docker Engine plus the compose plugin cover the remaining work. The self-host doc ask for Docker Engine 26 or newer, API 1.45 or newer, for bot home volume subpaths, together with curl and OpenSSL. Your user also must fit reach the daemon. If docker ps answer permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock, add your user to the docker group and open new login shell. First understand wetin this permission give: membership of docker be equivalent to root for the machine, because anybody for that group fit start container wey mount the host filesystem.

.env set up, then Postgres start

cp .env.example .env
chmod 600 .env

Anything start before plenty values must change. .env.example come with 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 and SANDBOX_SUPERVISOR_TOKEN=replace-with-32-plus-character-supervisor-token already set, but e leave POSTGRES_PASSWORD and POSTGRES_APP_PASSWORD empty. Repository publish every one of these placeholders, so if deploy leave any one, secret wey anybody fit read go dey active. Give each one different random value. ENCRYPTION_KEY must be 64 random hex characters. Na exactly that openssl rand -hex 32 dey print. The other secrets need 32 characters or more, so run the base64 line once for each one. For the two Postgres passwords, the self-host doc require URL-safe values. The last line dey give you that, so run am once for each password. The database get two logins. DATABASE_MIGRATION_URL come as postgres://rakazo:REPLACE_WITH_POSTGRES_PASSWORD@127.0.0.1:5433/rakazo, the owner wey dey run migrations, and DATABASE_URL come as postgres://rakazo_app:REPLACE_WITH_POSTGRES_APP_PASSWORD@127.0.0.1:5433/rakazo, the app's own login. E no get superuser rights, and row-level security dey control am. Put each password inside its own URL. pnpm db:migrate create the rakazo_app login with the password wey you set.

openssl rand -base64 48
openssl rand -hex 32
openssl rand -hex 24

Then start the database by itself and run the migrations.

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:build

pnpm sandbox:build build the bot computer image, wey package.json define as docker build -t rakazo/computer:local infra/sandboxes/computer. Na graphical image, so the first build go download plenty files and take time. Confirm say e land with docker image ls rakazo/computer. E suppose print one row.

The base compose file no publish any Postgres port. The docker-compose.postgres-host.yml overlay for that command publish am as 127.0.0.1:5433, and na loopback only, so host-side tools like pnpm db:migrate and pnpm dev fit reach am. Leave am like that. Compose no go start Postgres without POSTGRES_PASSWORD inside .env, but Postgres port wey internet fit reach go invite password attacks. The production compose file dey read the same variable and no publish any database port.

The first run

pnpm dev

That one start four things: the API for port 3100, the Graphile Worker, the Vite web app for 5173, and the sandbox supervisor for 7091 by default. If those ports busy, pnpm dev go choose another free block and print the URLs. For the default ports, the app dey at http://127.0.0.1:5173, and you suppose see sign-in page.

For VPS, you no dey sit for that machine, and you no suppose publish 5173 to reach am. Forward the ports through SSH (secure shell) from your own machine instead.

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

Pay attention to the difference between the ways to run this. pnpm dev dey run Vite for the host, bound locally. The development compose file get web service wey publish 127.0.0.1:5173:5173, and e get api service wey 127.0.0.1:3100:3100, both for loopback only, so the same tunnel go work for am. For the production file, the web app no publish any host port and e only expose 5173 to containers for its own networks. Na Caddy alone publish ports 80 and 443, so use the production file and its reverse proxy for anything wey you leave running.

Server deka sandbox provider safe?

Na this setting you must get right. SANDBOX_PROVIDER for .env na docker by default, and the pinned checkout still support Railway together with the providers we list for the self-host doc.

  • docker na the default. Bot computers dey run as containers for your machine, built from image pnpm sandbox:build wey produce am and run am under a supervisor. Bots for one workspace dey share one Team Computer by default, and bot only get container of its own for Private Computer. You no need E2B account.
  • e2b dey run the bot computers for E2B and e need E2B_API_KEY. For v0.3.5, the factory accept am for production when you supply the key, without any NODE_ENV restriction. The self-host doc say e fit public or multi-user production, because e keep bot computers away from the host wey dey run your API and database.
  • daytona, createos and boat na other remote providers, and each one need its own key: DAYTONA_API_KEY, CREATEOS_SANDBOX_API_KEY or BOAT_API_KEY.
  • railway dey run computers for Railway and e need RAILWAY_API_TOKEN plus explicitly selected RAILWAY_ENVIRONMENT_ID for the API and worker. Use dedicated Railway project or environment for sandboxes.
  • desktop dey run the bot commands directly for the API and worker host, as the doc talk am. For v0.3.5, the API and worker refuse am unless NODE_ENV be development or test, but .env.example ships NODE_ENV=development, so server wey dey run pnpm dev still accept am. No enable am for public or shared service.
  • fake na emulator for verification only. E no be runtime.
  • none dey start the product without any computer host.

Take this exactly as e be. For desktop mode, no isolation boundary dey at all. So the bot dey run shell commands as the user wey dey run the API process, with that user's home directory, SSH keys, cloud credentials and .env. Text wey bot read for web page fit become command for your server. Desktop mode for server na how bot fit hold your credentials. Use am for machine wey you dey sit in front of, or no use am at all. Switching providers put container around that web page path instead of closing am, and giving bot its own SearXNG search backend cover the same injection surface from the search side.

docker na real boundary between bots and your host, but e weak between the bots themselves. By default dem share one Team Computer, and the computer runtime doc say Team bots share the OS user, workspace, browser profiles, plus shell and X11 access. E also say per-bot folders na for organizing work, but dem no be security boundaries. So any Team bot fit read files from another Team bot. Bot wey need its own walls should use Private Computer, wey the docker provider run as separate sibling container for its own network. But the supervisor wey dey create those containers mount /var/run/docker.sock, and the self-host doc talk am clearly: access to that socket mean say person get control of the Docker host. So keep the supervisor private. .env.example treat SANDBOX_SUPERVISOR_TOKEN as dedicated credential, separate from BETTER_AUTH_SECRET, wey Docker sandboxes need outside local development, and e ships with placeholder wey anybody fit read for GitHub. Give am its own random value. For the strongest separation wey dey available here, use e2b, or give Rakazo machine wey no dey hold anything else. Na the same reason behind running coding agents inside disposable VM: the cheapest way to survive agent wey do something wrong na make sure say its machine no get value.

Model API keys go for where?

Rakazo optional model-credit billing dey off unless both Stripe secrets dey set. Na you go bring the key. .env.example dey set PI_DEFAULT_PROVIDER=openrouter, so OPENROUTER_API_KEY na the usual place, and provider keys dey work through the same setting.

Keep the key for .env and no put am for any file wey you commit. Both compose commands for the repository dey pass --env-file .env, so values dey reach the containers without dem ever write am into YAML wey git dey track. You fit also leave OPENROUTER_API_KEY empty and connect a model for the app after signup. Na one more reason why ENCRYPTION_KEY need real random value instead of the placeholder wey ship with am.

Set spending limit for the key with the provider before any bot use am. Bot wey dey loop na bot wey dey spend money. Rakazo also provide MAX_TOOL_CALLS_PER_TURN: set positive integer to soft-stop turn wey pass e tool-call budget, while e still produce final assistant message. If you no set am, e empty, or na 0, e remain unlimited. This dey count tool calls, no be money, so e no replace provider spending limit. Give this key e own name so you fit revoke am alone. If na team setup you dey do instead of personal setup, OneCLI one gateway wey dey front of everybody agent na another answer to the same problem, because e keep provider keys for one place instead of one key per person.

Going from dev mode to something wey you fit leave dey run

The repository get a production compose file wey dey run Postgres, the API, the worker, the web app, and Caddy for TLS (transport layer security) certificates wey e dey obtain automatically. Caddy na the only service for inside wey dey publish ports. E default to E2B for the bot computers. An opt-in overlay, infra/compose/docker-compose.prod.docker.yml, dey run local Docker computers for the same stack instead, and the doc warn say the supervisor wey e add get root-equivalent power for the host.

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/health

Create a key-only deploy account and confirm say you fit log in with am before you run the script. harden-host.sh disable SSH password and root login, rate-limit SSH, add SSH, HTTP and HTTPS allowances through UFW (uncomplicated firewall) while e preserve existing private-network rules, and turn on fail2ban, unattended security updates, AppArmor and audit rules. E no go run without SSH_CONNECTION, na why the command pass am through sudo, and e go roll back the firewall change unless you confirm am from a fresh SSH session within three minutes. Read am before you run am, because e change how you dey log in and reload SSH. Keep your provider's console open until fresh SSH login succeed.

The production .env need more than the development one. The self-host doc list this minimum, plus the 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>

Point an A record to the server before that first up. Caddy request certificate for the name inside RAKAZO_HOST; the name must resolve to this box, and either port 80 for HTTP validation or port 443 for TLS-ALPN validation must dey accessible from outside. Both challenges dey enabled by default, so closing port 80 alone no prevent certificate issuance through port 443.

Keep SIGNUP_ALLOWLIST set to your own address from the start. .env.example ship SIGNUPS_ENABLED=true, and both settings dey read from the environment every time API start, so an instance for public name with signups on and no allowlist go accept registrations from anybody wey find am. A non-empty allowlist dey apply every time e start and e replace the stored list. Allowlisted signup need mailbox verification, including the first account, so set up email delivery before you register. Without email, the doc route na to start with SIGNUPS_ENABLED=false and create your account with the server-side bootstrap command wey e give, which create an ordinary verified account without server privileges. Put allowlist first. You fit relax am later if you want. If you already dey run several services for the same box and you prefer to keep one list of people instead of one allowlist per app, put an Authentik instance in front of dem go move that decision to the proxy, though e dey sit in front of Rakazo's own Better Auth accounts instead of replacing dem.

Treat docs/self-host.md for the repository as the authority for production settings, because e dey change with the code and this guide no dey change with am. Since Compose dey handle the work, the normal rules apply, and the Docker Compose basics for a VPS explain why --env-file and named volumes matter more once a stack become something wey you leave alone for months.

Backups

Postgres and the data/ directory dey hold the instance data for this setup. Recovery still need ENCRYPTION_KEY and any content master keys wey you configure, so keep copies for outside the server.

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

backup.sh dey dump Postgres and archive data/. restore.sh dey work for the development Compose stack, inside an empty database, while the application services dey stopped. E no dey read the production backup files. For machine wey you depend on, install infra/compose/backup-prod.sh as /usr/local/sbin/rakazo-backup together with the timer wey the repository supply. E dey write one verified dump and one app-data archive to /var/backups/rakazo. By default, e dey keep up to three verified snapshots. RAKAZO_BACKUP_KEEP dey set this number. RAKAZO_BACKUP_MAX_GB dey set the 50 GiB limit. Before each run, e dey remove partial snapshots and excess history, so rotation happen by itself. E fit also encrypt each backup with age for the public recipients wey you list inside /etc/rakazo/backup.env. This one make the server write backups wey e no fit read. Generate that key pair for machine wey you control, and keep the private key outside the server. If recipients no dey, the backup remain plaintext and the logs go show warning. But after the first encrypted backup, any run without recipients go fail unless you explicitly allow plaintext with RAKAZO_BACKUP_ALLOW_PLAINTEXT=1. Backup wey dey on the same disk with the database no be backup, so copy am comot from the server. Then restore am once for spare server before you need am.

Why e no work, and wetin you go see

pnpm db:migrate no fit reach database. The migration report say e no fit reach database server for 127.0.0.1:5433. Either Postgres container no dey up, e dey up but e never ready, or dem start am without docker-compose.postgres-host.yml overlay, wey dey publish 5433 to the host. Run docker compose --env-file .env -f infra/compose/docker-compose.yml ps and check for postgres service wey dey report healthy, because compose file give am health check wey dey run every three seconds. If container dey restart nonstop, read im logs: the pinned Compose stack no go start for old Postgres 16 volume until dem migrate am to Postgres 18. docker compose ... down -v go clear am, and e go delete the data together with am.

Port don already dey occupied. Bringing up Postgres fail with bind: address already in use when another thing dey hold 5433, most times na old Rakazo stack wey you forget stop. sudo ss -lntp | grep 5433 go show the process name. The overlay dey read host port from POSTGRES_HOST_PORT, so you fit change am, as long as DATABASE_URL and DATABASE_MIGRATION_URL change together with am.

Bot no ever get computer. With SANDBOX_PROVIDER=docker and no rakazo/computer:local image, nothing dey to start. docker image ls rakazo/computer go answer this for one line, and pnpm sandbox:build go fix am. If supervisor no fit reach Docker socket, e no fit create containers too, and the message go show the path: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock.

Long command dey die halfway. .env.example set SANDBOX_COMMAND_TIMEOUT_MS=300000, so one command inside bot computer go stop after five minutes. Increase am for slow builds instead of assuming say sandbox crash.

pnpm install dey fail for confusing ways. Check node -v before anything else. The workspace declare ^22.22.2 || ^24.0.0 || >=26.0.0, so 23.x, 25.x and any 22.x before 22.22.2 no dey inside the supported range. The pinned .npmrc set engine-strict=true, so pnpm install go reject unsupported Node version with engine/version error before application dependency code run.

Sign-in dey work locally but e no work through domain. BETTER_AUTH_URL, WEB_ORIGIN and API_URL all need get the same public origin as the address bar, including the scheme. Stale http://127.0.0.1:5173 wey remain for one of dem na the usual reason why session no dey stay active.

Updating a pinned checkout

Upgrade path for the self-host doc wey cover production Compose stack built from your checkout short: pull the new source, then rebuild and restart the API, the worker, and the web app. Migrations run when the API starts, because its start command applies dem before e begin serve.

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 web

Back up first. Migrations dey move forward, and beta no give you any reverse path wey you fit trust. If your checkout old pass 30 August 2026, and this includes the v0.1.0-beta commit, read the doc note about the 20260830200000_space_scope_names_and_user_credentials migration before you upgrade. Na coordinated cutover, so stop the old API and worker first, then run the Space privacy-boundary check wey the doc provide. If you dey upgrade from checkout wey come before the separate app login, set POSTGRES_APP_PASSWORD inside .env before rebuilding; the production Compose file no go start without am. The source-checkout and production Compose files also dey run Postgres 18: existing Postgres 16 installation need the doc infra/compose/upgrade-postgres.sh procedure before e fit start for the new layout. Read the commits between your pinned SHA and the new one before you take dem, because project wey still young like this fit rename environment variables without announcement, and missing variable go show as service wey starts and then exits. If you still dey decide whether Rakazo na the correct thing to run at all, roundup of self-hosted AI agents covers wetin else dey this category and wetin each one costs to keep alive.

FAQ

I fit run Rakazo for 1 GB VPS?

No. Postgres, the API, the worker, the sandbox supervisor, and the web app all dey run at the same time. With SANDBOX_PROVIDER=docker, the bots' computer add one container wey hold graphical desktop, with separate X display and Chrome process for every active bot. All of dem dey inside one default limit of 2 GB memory and two CPUs. The self-host doc for v0.3.5 no specify host size. Treat 4 GB as the minimum for the control plane, and use more when the desktops dey run for your machine.

Desktop sandbox provider safe for server?

No. The self-host doc say desktop dey run commands directly for the API and worker host. This mean say the bot dey act as the user wey run that process, with access to that user's files and credentials. For v0.3.5, the API and worker reject am outside development and test mode. But server wey dey run pnpm dev dey for development mode and go accept am. Keep am away from any public or shared server. Use docker to give bot a Private Computer when e must not share files with the workspace's other bots, or use e2b when more than one person dey sign in.

Which Rakazo version I suppose install?

As of 9 November 2026, the newest release na v0.8.0, wey dem publish on 4 November 2026 and mark Latest. To follow this guide, check out the pinned v0.3.5 commit, f31e3c0699f086d663637c4107858c238a086fb3, instead of tracking main or the August v0.1.0-beta prerelease. Branch fit change under you and tag fit get new pointer, so none of dem identify tree wey you fit return to. Record the commit, because rollback only possible when you know which one dey work.

Where I suppose put my OpenRouter API key?

Put am for .env as OPENROUTER_API_KEY, and never put am inside compose file wey you commit. Both compose commands for the repository pass --env-file .env, so the value reach the containers without writing am into tracked YAML. You fit also leave am empty and connect model inside the app after signup. Set spending limit for the key with the provider, because bot wey enter loop go continue calling the model until something stop am.

I need domain name and TLS?

For anything beyond first test, yes. The production compose file run Caddy and obtain certificates automatically. Set RAKAZO_HOST to the public hostname, and set BETTER_AUTH_URL, WEB_ORIGIN and API_URL to the same public HTTPS origin. For first look, you fit skip the domain: run pnpm dev and forward port 5173 through SSH instead of publishing am.

Dis article help you?