Rakazo install guide (tested end-to-end)

This is the full record of our own deployment on a real server (4 cores / 8 GB / ARM): about 25–40 minutes when things go smoothly. Read the three traps first (steps 5–7) — most people don't get stuck on installing; they get stuck there.

Step 0: What you need

A VPS (4 cores / 8 GB RAM / 80 GB disk is a comfortable start; hourly-billed tiers let you test cheaply; ARM tiers are verified to work, browser sandbox included), a domain or subdomain (a temporary address works for a first test), and a model account — a Claude/ChatGPT subscription or an API key.

Step 1: Install Docker

curl -fsSL https://get.docker.com | sh
docker --version && docker compose version

We tested on Ubuntu 24.04 LTS with Docker 29.x / Compose v5.x.

Step 2: Run the official installer

Only ever use the installer from the official repository elie222/rakazo — no third-party variants:

mkdir -p ~/rakazo && cd ~/rakazo
curl -fsSLO https://raw.githubusercontent.com/elie222/rakazo/main/infra/compose/install-images.sh
bash install-images.sh --prepare-only   # generate .env first
bash install-images.sh                  # full install

When the installer finishes, postgres / api / worker / supervisor / web should all report Healthy, and http://127.0.0.1:5173 on the server should return 200.

Step 3: HTTPS (Caddy reverse proxy)

Set RAKAZO_HOST / BETTER_AUTH_URL / WEB_ORIGIN / API_URL in .env to your final https address, re-run the installer, then proxy with Caddy:

# /etc/caddy/Caddyfile
bot.example.com {
    reverse_proxy 127.0.0.1:5173
}

Done when the login page loads over https with a valid certificate. Desktop and mobile clients later connect to this https address as an existing instance.

Step 4: Take a baseline backup

docker exec rakazo-postgres-1 sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB"' | gzip > backup-base.sql.gz

Back up the empty baseline now, and repeat before every upgrade — a restore takes about two minutes and wipes away upgrade regret.

Step 5 (trap 1): "Email not verified" after signup

This is a known default-deployment behaviour: with no SMTP configured, verification emails are never sent, so a fresh account is always stuck — you did nothing wrong. Two proper fixes: configure SMTP properly (the long-term answer), or, for a single-user setup, have an admin mark the owner's email as verified directly in the database (the stopgap). Sort this before moving on.

Step 6 (trap 2): Connecting the model is your job only

Inside rakazo, connect your model account yourself: subscription OAuth needs your own login plus MFA, and an API key should be a fresh dedicated key created by you and pasted by you. Never send passwords, codes, or full keys to anyone — including whoever helps you deploy.

Step 7 (trap 3): Close public signups immediately

# in .env, then re-run the installer
SIGNUPS_ENABLED=false
SIGNUP_ALLOWLIST=your-owner-email

Verify: submitting the signup form is now rejected, and the owner can still log in.

Step 8: Accept your first bot

Create a bot and test three things with one message (this is the exact test we used):

Hi! Three quick tasks: 1) Remember my code word: BANANA-42. I will ask you for it later.
2) Use your computer: list the files in your home folder, then create a file named
hello-test.txt there and write today's date in it. 3) Tell me the current time in Berlin.
Report the result of each task.

If all three pass, ask What was my code word? — a correct answer proves memory and tool use are genuinely working. Your AI teammate is on duty.

Stuck?

Or skip all of the above: our deployment service is literally this guide, executed for you — guided from $49, done-for-you $149.

Based on the October 2026 rakazo version and our test environment. The project moves fast — if commands or UI differ, the official docs win.