Self-host Rakazo: your own AI bot on a VPS
Run Rakazo on your own VPS: Node 22, pnpm, Postgres and Graphile Worker in Docker Compose, the sandbox provider choice, key handling, and honest sizing.
What self-hosting Rakazo actually runs
Self-hosting Rakazo means running five things on one Linux server: PostgreSQL, a Graphile Worker process, the API, the web app, and a sandbox container that serves as the bots' computer. Rakazo is an open-source alternative to Grok Bot, published by elie222 under the Apache 2.0 licence. Each bot gets its own conversations, memory, routines and history, shares one Team Computer with the workspace's other bots unless it is given a Private Computer, and can spawn peers or short-lived subagents. If words like memory, subagent and tool call are doing unfamiliar work in that sentence, a staged path through how agents actually work is worth an afternoon first, because most of the settings below only make sense once you can picture what a bot is doing when it wakes up.
That last part is why this belongs on a VPS (virtual private server) and not on a desktop. A bot that holds memory and runs scheduled work has to be reachable while you sleep. A laptop that suspends drops the queue.
Rakazo still describes itself as beta as of October 2026, even though it now publishes stable-numbered releases, so treat this as a working setup rather than a finished appliance. The stack is 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 stores its queue inside Postgres, so there is no Redis and no second data store to run. .env.example sets WAKEUP_DRIVER=graphile, which means a bot waking up is a Postgres-backed job. Stop Postgres and every scheduled bot action stops with it. If you would rather assemble an agent from parts instead of running someone else's product, building your own agent from components is the other route.
Why a 1 GB plan will not hold this
Count the processes. Postgres is one. The API is a Node process. The worker is a second. The web app is a third. The sandbox supervisor is a fourth. Then comes the bots' computer: by default one shared Team Computer container holding a graphical Linux desktop, with a separate X display and Chrome process for every bot that is active.
The project's self-host doc no longer gives a host size. The doc at v0.3.5, checked on 27 October 2026, lists software requirements only. What it does give is a per-computer ceiling: with Docker sandboxes, RAKAZO_COMPUTER_MEMORY defaults to 2g and RAKAZO_COMPUTER_CPUS to 2. That ceiling applies to each computer, not to each bot. Each workspace gets one Team Computer by default, and every active Team bot runs its desktop and browser inside it, so all of them share those 2 GB and two cores. Only a bot moved to a Private Computer gets a container, and a ceiling, of its own. Set SANDBOX_PROVIDER=docker and those desktops move onto your VPS, on top of the control plane, so 4 GB is a floor rather than a target. Start at 8 GB if you plan to keep more than one bot awake, raise RAKAZO_COMPUTER_MEMORY so the shared computer can actually use that memory, and measure the real number with docker stats while the bots work. The browser inside the sandbox is what moves the memory line, so a spec sheet will not tell you. To stop a small box from running too many browsers at once, set a positive SANDBOX_TEAM_SCREEN_LIMIT, which caps active desktops on a Docker Team Computer. The shipped 0 leaves it uncapped. If memory is tight overall, RAKAZO_COMPUTER_MEMORY also accepts a smaller value such as 1536m. For the general method of sizing a box for agent work, how much RAM and CPU an agent VPS actually needs goes through the measurement in detail.
One setting keeps this from getting worse. .env.example ships SANDBOX_IDLE_MS=600000, and its comment says computers are paused or stopped after that many idle milliseconds. Ten minutes idle and the computer goes away. The minimum accepted value is 30000, and 0 disables idle sleep. The same comment suggests 0 for Docker self-hosts, where an idle computer costs nothing, so long-running apps and sessions stay up. That holds for money, not memory. On a small VPS, leave the timer on, because without it every computer you ever started, and every browser inside it, keeps running.
Disk counts too. The sandbox image, the Node modules and the Postgres volume share one disk, so 40 GB is a sensible starting point.
Pin a version before you clone
Rakazo moves fast and main is not a release. As of 9 November 2026, v0.8.0, published on 4 November 2026, is the release marked Latest. This guide remains pinned to v0.3.5, published on 25 October 2026.
git clone https://github.com/elie222/rakazo.git
cd rakazo
git checkout f31e3c0699f086d663637c4107858c238a086fb3
git log -1 --format='%H %ci'That commit is the one v0.3.5 points at. Pin the commit rather than the branch or the tag. A branch changes under you on the next git pull, and a tag is a movable label that a maintainer can repoint, so neither one identifies a tree you can return to. A commit identifier cannot move. Write yours down next to your other server facts, because when an upgrade breaks the cheap fix is git checkout <old commit> and a rebuild, and that only works if you know which commit was working. The pinned README calls Rakazo beta, so pinning this precisely is worth the small effort. A project with a long record of deliberate releases can be held at a published tag instead, which is what a smaller self-hosted stack like openGym does.
Requirements: Node 22, pnpm 9, and Docker
node -v
pnpm -v
docker --versionpackage.json declares "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 a later 22.x, any v24, or v26 and up. A v22 older than 22.22.2 is outside that range, and the README says outright that Node.js 23.x and 25.x are not supported. Install a supported Node version from NodeSource or nvm. Corepack ships with Node 22 and 24; on Node 26 and up, install it first with npm install -g corepack. Then activate pnpm:
corepack enable
corepack prepare pnpm@9.15.0 --activateDocker Engine plus the compose plugin covers the rest. The self-host doc asks for Docker Engine 26 or newer, API 1.45 or newer, for bot home volume subpaths, along with curl and OpenSSL. Your user also has to be able to reach the daemon. If docker ps answers 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 a new login shell. Know what that grants first: membership in docker is equivalent to root on the machine, because anyone in that group can start a container that mounts the host filesystem.
Configure .env, then start Postgres
cp .env.example .env
chmod 600 .envSeveral values must change before anything starts. .env.example ships 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, and it leaves POSTGRES_PASSWORD and POSTGRES_APP_PASSWORD empty. Every one of those placeholders is published in the repository, so a deploy that keeps one is running on a secret anyone can read. Give each its own random value. ENCRYPTION_KEY must be 64 random hex characters, which is exactly what openssl rand -hex 32 prints. The other secrets take 32 or more characters, so run the base64 line once for each. For the two Postgres passwords the self-host doc asks for URL-safe values, which the last line gives you, so run it once for each as well. The database has two logins. DATABASE_MIGRATION_URL ships as postgres://rakazo:REPLACE_WITH_POSTGRES_PASSWORD@127.0.0.1:5433/rakazo, the owner that runs migrations, and DATABASE_URL as postgres://rakazo_app:REPLACE_WITH_POSTGRES_APP_PASSWORD@127.0.0.1:5433/rakazo, the app's own login, which has no superuser rights and is held to row-level security. Put each password into its own URL. pnpm db:migrate creates the rakazo_app login with the password you set.
openssl rand -base64 48
openssl rand -hex 32
openssl rand -hex 24Then bring up the database on its own 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:buildpnpm sandbox:build builds the bot computer image, defined in package.json as docker build -t rakazo/computer:local infra/sandboxes/computer. It is a graphical image, so the first build pulls a lot and takes time. Confirm it landed with docker image ls rakazo/computer, which should print one row.
The base compose file publishes no Postgres port at all. The docker-compose.postgres-host.yml overlay in that command publishes it as 127.0.0.1:5433, which is loopback only, so host-side tools like pnpm db:migrate and pnpm dev can reach it. Leave it that way. Compose refuses to start Postgres without a POSTGRES_PASSWORD in .env, but a Postgres port reachable from the internet invites password attacks. The production compose file reads the same variable and publishes no database port.
The first run
pnpm devThat starts four things: the API on port 3100, the Graphile Worker, the Vite web app on 5173, and the sandbox supervisor on 7091 by default. If those ports are busy, pnpm dev selects another free block and prints the URLs. At the default ports, the app is at http://127.0.0.1:5173, and you should get a sign-in page.
On a VPS you are not sitting at that machine, and you should not publish 5173 to reach it. Forward the ports over 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-serverBe careful with the difference between the ways of running this. pnpm dev runs Vite on the host, bound locally. The development compose file's web service publishes 127.0.0.1:5173:5173 and its api service 127.0.0.1:3100:3100, both loopback only, so the same tunnel works for it. In the production file the web app publishes no host port and only exposes 5173 to the containers on its own networks, and Caddy alone publishes ports 80 and 443, so use the production file and its reverse proxy for anything you leave running.
Which sandbox provider is safe on a server?
This is the one setting to get right. SANDBOX_PROVIDER in .env is docker by default, and the pinned checkout also supports Railway alongside the providers listed in the self-host doc.
dockeris the default. Bot computers run as containers on your machine, built from the imagepnpm sandbox:buildproduced and run under a supervisor. A workspace's bots share one Team Computer by default, and a bot gets a container of its own only on a Private Computer. No E2B account is needed.e2bruns the bot computers on E2B and needsE2B_API_KEY. Atv0.3.5the factory accepts it in production when the key is supplied, with noNODE_ENVrestriction. The self-host doc calls it suited to public or multi-user production, because it keeps bot computers away from the host running your API and your database.daytona,createosandboatare further remote providers, each needing its own key:DAYTONA_API_KEY,CREATEOS_SANDBOX_API_KEYorBOAT_API_KEY.railwayruns computers on Railway and needsRAILWAY_API_TOKENand an explicitly selectedRAILWAY_ENVIRONMENT_IDon the API and worker. Use a dedicated Railway project or environment for sandboxes.desktopruns the bot's commands directly on the API and worker host, as the doc puts it. Atv0.3.5the API and worker refuse it unlessNODE_ENVisdevelopmentortest, but.env.exampleshipsNODE_ENV=development, so a server runningpnpm devstill accepts it. Do not enable it on a public or shared service.fakeis an emulator for verification only. It is not a runtime.nonestarts the product with no computer host at all.
Take that literally. In desktop mode there is no isolation boundary at all, so the bot runs shell commands as the user running the API process, with that user's home directory, that user's SSH keys, that user's cloud credentials and that user's .env. Text in a web page the bot reads becomes a command on your server. Desktop mode on a server is how a bot ends up holding your credentials. Use it on a machine you sit at, or not at all. Switching providers puts a container around that web page path rather than closing it, and giving a bot its own SearXNG search backend covers the same injection surface from the search side.
docker is a real boundary between the bots and your host, and a weak one between the bots themselves. By default they share a single Team Computer, and the computer runtime doc says Team bots share the OS user, the workspace, browser profiles and shell and X11 access, and that the per-bot folders organize work but are not security boundaries. So any Team bot can read another Team bot's files. A bot that needs its own walls goes on a Private Computer, which the docker provider runs as a separate sibling container on its own network. The supervisor that creates those containers, though, mounts /var/run/docker.sock, and the self-host doc says it plainly: access to that socket is equivalent to control of the Docker host. So keep the supervisor private. .env.example treats SANDBOX_SUPERVISOR_TOKEN as a dedicated credential, distinct from BETTER_AUTH_SECRET, that Docker sandboxes require outside local development, and it ships with a placeholder anyone can read on GitHub. Give it its own random value. For the strongest separation available here, use e2b, or give Rakazo a machine that holds nothing else. That is the same reasoning behind running coding agents in a disposable VM: the cheapest way to survive an agent doing something wrong is for its machine to be worth nothing.
Where do model API keys go?
Rakazo's optional model-credit billing stays off unless both Stripe secrets are set. You bring the key. .env.example sets PI_DEFAULT_PROVIDER=openrouter, so OPENROUTER_API_KEY is the usual place, and provider keys work through the same setting.
Keep the key in .env and out of any file you commit. Both compose commands in the repository pass --env-file .env, so values reach the containers without ever being written into YAML that git tracks. You can also leave OPENROUTER_API_KEY empty and connect a model in the app after signup, which is one more reason ENCRYPTION_KEY needs a real random value rather than the shipped placeholder.
Set a spending limit on the key at the provider before a bot ever uses it. A bot that loops is a bot that spends. Rakazo also provides MAX_TOOL_CALLS_PER_TURN: set a positive integer to soft-stop a turn that exceeds its tool-call budget while still producing a final assistant message. Unset, empty or 0 leaves it unlimited. This counts tool calls, not money, so it does not replace the provider's spending limit. Give this key its own name so you can revoke it alone. If you are setting this up for a team rather than for yourself, OneCLI's one gateway in front of everyone's agent is a different answer to the same problem, because it keeps provider keys in one place instead of one per person.
Going from dev mode to something you can leave running
The repository ships a production compose file that runs Postgres, the API, the worker, the web app, and Caddy for TLS (transport layer security) certificates it obtains automatically. Caddy is the only service in it that publishes ports. It defaults to E2B for the bot computers. An opt-in overlay, infra/compose/docker-compose.prod.docker.yml, runs local Docker computers on the same stack instead, and the doc warns that the supervisor it adds is root-equivalent on 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/healthCreate a key-only deploy account and confirm you can log in with it before running the script. harden-host.sh disables SSH password and root login, rate-limits SSH, adds SSH, HTTP and HTTPS allowances through UFW (uncomplicated firewall) while preserving existing private-network rules, and turns on fail2ban, unattended security updates, AppArmor and audit rules. It refuses to run without SSH_CONNECTION, which is why the command passes it through sudo, and it rolls the firewall change back unless you confirm it from a fresh SSH session within three minutes. Read it before you run it, because it changes how you log in and reloads SSH. Keep your provider's console open until a fresh SSH login succeeds.
The production .env needs more than the development one. The self-host doc lists 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 at the server before that first up. Caddy requests a certificate for the name in RAKAZO_HOST; the name must resolve to this box, and either port 80 for HTTP validation or port 443 for TLS-ALPN validation must be externally accessible. Both challenges are enabled by default, so closing port 80 alone does not prevent certificate issuance through port 443.
Keep SIGNUP_ALLOWLIST set to your own address from the start. .env.example ships SIGNUPS_ENABLED=true, and both settings are read from the environment on every API start, so an instance on a public name with signups on and no allowlist accepts registrations from whoever finds it. A non-empty allowlist is applied on every start and replaces the stored list. Allowlisted signup requires mailbox verification, the first account included, so set up email delivery before you register. Without email, the doc's route is to start with SIGNUPS_ENABLED=false and create your account with the server-side bootstrap command it gives, which makes an ordinary verified account with no server privileges. Allowlist first. Relax it later if you want to. If you already run several services on the same box and would rather keep one list of people than one allowlist per app, putting an Authentik instance in front of them moves that decision to the proxy, though it sits in front of Rakazo's own Better Auth accounts rather than replacing them.
Treat docs/self-host.md in the repository as the authority for production settings, because it changes with the code and this guide does not. Since Compose is doing the work, the ordinary rules apply, and the Docker Compose basics for a VPS cover why --env-file and named volumes matter more once a stack is something you leave alone for months.
Backups
Postgres and the data/ directory hold the instance's data in this setup; recovery also needs ENCRYPTION_KEY and any configured content master keys, so keep copies off the server.
./scripts/backup.sh
./scripts/restore.sh backups/BACKUP_TIMESTAMPbackup.sh dumps Postgres and archives data/. restore.sh works on the development Compose stack, into an empty database with the application services stopped, and it does not read the production backup files. For a machine you depend on, install infra/compose/backup-prod.sh as /usr/local/sbin/rakazo-backup with the timer the repository supplies. It writes a verified dump and an app-data archive to /var/backups/rakazo, keeps up to three verified snapshots by default, set by RAKAZO_BACKUP_KEEP, within a 50 GiB cap set by RAKAZO_BACKUP_MAX_GB, and clears partial snapshots and excess history before each run, so rotation happens without you. It can also encrypt each backup with age to public recipients you list in /etc/rakazo/backup.env, so the server writes backups it cannot read. Generate that key pair on a machine you control and keep the private key off the server. Without recipients the backup stays plaintext and logs a warning, but after the first encrypted backup a run without recipients fails unless you explicitly allow plaintext with RAKAZO_BACKUP_ALLOW_PLAINTEXT=1. A backup sitting on the same disk as the database is not a backup, so copy it off the box. Then restore it once, on a spare server, before you need it.
Why it fails, and what you will see
pnpm db:migrate cannot reach the database. The migration reports that it cannot reach the database server at 127.0.0.1:5433. Either the Postgres container is not up, it is up and not ready yet, or it was started without the docker-compose.postgres-host.yml overlay, which is what publishes 5433 to the host. Run docker compose --env-file .env -f infra/compose/docker-compose.yml ps and look for the postgres service reporting healthy, because the compose file gives it a health check that runs every three seconds. If the container restarts in a loop, read its logs: the pinned Compose stack refuses to start on an old Postgres 16 volume until it has been migrated to Postgres 18. docker compose ... down -v clears it, and it deletes the data with it.
The port is already taken. Bringing up Postgres fails with bind: address already in use when something else holds 5433, most often an earlier Rakazo stack you forgot to stop. sudo ss -lntp | grep 5433 names the process. The overlay reads the host port from POSTGRES_HOST_PORT, so you can move it, as long as DATABASE_URL and DATABASE_MIGRATION_URL move with it.
A bot never gets a computer. With SANDBOX_PROVIDER=docker and no rakazo/computer:local image, there is nothing to start. docker image ls rakazo/computer answers that in one line, and pnpm sandbox:build fixes it. If the supervisor cannot reach the Docker socket it cannot create containers either, and the message names the path: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock.
A long command dies partway. .env.example sets SANDBOX_COMMAND_TIMEOUT_MS=300000, so a single command inside a bot's computer is cut off after five minutes. Raise it for slow builds instead of assuming the sandbox crashed.
pnpm install breaks in confusing ways. Check node -v before anything else. The workspace declares ^22.22.2 || ^24.0.0 || >=26.0.0, so 23.x, 25.x and any 22.x before 22.22.2 are all outside it. The pinned .npmrc sets engine-strict=true, so pnpm install rejects an unsupported Node version with an engine/version error before application dependency code runs.
Sign-in works locally but not through the domain. BETTER_AUTH_URL, WEB_ORIGIN and API_URL all have to hold the same public origin as the address bar, scheme included. A stale http://127.0.0.1:5173 left in one of them is the usual cause of a session that never sticks.
Updating a pinned checkout
The upgrade path in the self-host doc for a production Compose stack built from your checkout is 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 them before it serves.
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 webBack up first. Migrations move forward, and a beta gives you no reverse path you can count on. If your checkout is older than 30 August 2026, which includes the v0.1.0-beta commit, read the doc's note on the 20260830200000_space_scope_names_and_user_credentials migration before you upgrade. It is a coordinated cutover, so stop the old API and worker first and run the Space privacy-boundary check the doc gives. When upgrading from a checkout that predates the separate app login, set POSTGRES_APP_PASSWORD in .env before rebuilding; the production compose file refuses to start without it. The source-checkout and production Compose files also run Postgres 18: an existing Postgres 16 installation needs the doc's infra/compose/upgrade-postgres.sh procedure before it can start on the new layout. Read the commits between your pinned SHA and the new one before taking them, because a project this young renames environment variables without announcing it, and a missing variable shows up as a service that starts and then exits. If you are still deciding whether Rakazo is the right thing to run at all, the roundup of self-hosted AI agents covers what else sits in this category and what each one costs to keep alive.
FAQ
Can I run Rakazo on a 1 GB VPS?
No. Postgres, the API, the worker, the sandbox supervisor and the web app all run at the same time, and with SANDBOX_PROVIDER=docker the bots' computer adds a container holding a graphical desktop, with a separate X display and Chrome process for every active bot, all inside one default ceiling of 2 GB of memory and two CPUs. The self-host doc at v0.3.5 gives no host size. Treat 4 GB as the floor for the control plane, and go higher when the desktops run on your machine.
Is the desktop sandbox provider safe on a server?
No. The self-host doc says desktop runs commands directly on the API and worker host, so the bot acts as the user running that process, with that user's files and credentials in reach. At v0.3.5 the API and worker refuse it outside development and test mode, but a server running pnpm dev is in development mode and accepts it. Keep it off any public or shared server. Use docker, giving a bot a Private Computer when it must not share files with the workspace's other bots, or e2b when more than one person signs in.
Which version of Rakazo should I install?
As of 9 November 2026 the newest release is v0.8.0, published 4 November 2026 and marked Latest. To follow this guide, check out the pinned v0.3.5 commit, f31e3c0699f086d663637c4107858c238a086fb3, rather than tracking main or the August v0.1.0-beta prerelease. A branch moves under you and a tag can be repointed, so neither identifies a tree you can return to. Record the commit, because rolling back is only possible when you know which one worked.
Where do I put my OpenRouter API key?
In .env as OPENROUTER_API_KEY, and never in a compose file you commit. Both compose commands in the repository pass --env-file .env, so the value reaches the containers without being written into tracked YAML. You can also leave it empty and connect a model in the app after signup. Set a spending limit on the key at the provider, because a bot in a loop keeps calling the model until something stops it.
Do I need a domain name and TLS?
For anything past a first test, yes. The production compose file runs Caddy and obtains certificates automatically; set RAKAZO_HOST to the public hostname and BETTER_AUTH_URL, WEB_ORIGIN and API_URL to the same public HTTPS origin. For a first look you can skip the domain: run pnpm dev and forward port 5173 over SSH instead of publishing it.