How to Self-Host a Controllable AI Assistant: Deploy Rakazo in 10 Minutes

AI assistants are everywhere, but pricing tiers and feature limits keep rising. Grok Bot, Meta Muse, OpenAI Dots—they're convenient, but you're at the mercy of policy changes. What if you could run a fully-featured AI assistant yourself, complete with persistent memory, cross-device sync, and the freedom to choose any model? This guide is here to show you exactly how. I'll walk you through deploying Rakazo—an open-source, self-hosted AI Agent—on any machine with Docker (Mac, Windows, Linux, or cloud). In about 10 minutes, you'll have it running, connected to your own API key, with your first Persistent Bot ready to go.

Prerequisites

Before starting, ensure your environment meets these requirements:

If you're on Mac or Windows with Docker Desktop installed, Compose is usually bundled. Linux users just need to verify docker compose version outputs correctly.

Step 1: One-Click Download & Service Startup

The official repo provides a one-click install script. No git clone or local Node.js setup required. Just create a directory, download the script, and run it:

mkdir -p rakazo && cd rakazo && \
curl -fsSLO https://raw.githubusercontent.com/elie222/rakazo/main/infra/compose/install-images.sh && \
bash install-images.sh

This script does three things:

1. Pulls the Docker Compose config from GitHub, defining the Web frontend, API service, Worker, Postgres containers, etc.
2. Automatically generates a .env file, pre-filled with randomly generated secure keys (database passwords, auth secrets, encryption keys, etc.).
3. Runs docker compose up, pulling images and starting all service containers.

You'll see download progress bars. Depending on your network, this takes 2–5 minutes. The script supports resuming; if it fails midway or you want to pull updated images later, just re-run it. It will preserve your existing .env configuration without overwriting it.

Network Restriction Note: If raw.githubusercontent.com is blocked, set the RAKAZO_DOWNLOAD_BASE environment variable to a mirror URL before running, or use the --local flag to skip downloading the Compose file (assuming you already have it manually placed).

Once started, open http://127.0.0.1:5173 in your browser. You'll see the Rakazo registration page. Create an account, and let's move to the crucial step.

Step 2: Connect Your Own Model

One of Rakazo's core strengths is its "Bring Your Own Model" approach. It doesn't lock you into a single provider. Instead, it uses an intermediary layer called Pi to let you seamlessly connect any supported API.

After your first login, the UI will guide you to connect a model. If you already have an OpenAI, Anthropic, or OpenRouter API key, enter it directly. If not, I highly recommend OpenRouter for testing—it aggregates nearly all major models, so one key lets you switch models on the fly, making debugging incredibly easy.

The connection process is straightforward:

1. Navigate to the model connection section in Settings.
2. Enter your API Key and the desired model identifier (e.g., openai/gpt-6.1-sol, anthropic/claude-sonnet-5.5).
3. Save and run a test conversation to verify responses.

Why this matters: You control the model, usage, and costs. If a provider changes pricing or experiences downtime, you can switch instantly in settings without migrating data or redeploying.

Step 3: Create Your First Persistent Bot

This is where it gets interesting. Unlike ChatGPT's ephemeral chats, Rakazo's Bots are persistent—each maintains its own conversation history, memory, and even scheduled routines. Think of it as your dedicated AI colleague.

Path: Login → Create a new bot → Name it (e.g., "Coding Assistant") → Save.

Once created, you'll enter the Bot's chat interface. Try a practical prompt:

Please write a Python quicksort function with unit tests.

Since you connected your own model in Step 2, you'll get a complete, accurate code response. Crucially, this conversation is saved. You can return later to follow up or iterate. This is the core value of Persistent Bots: zero context loss, uninterrupted memory.

Advanced: Deploy to a Cloud Server for Anywhere Access

Once running locally, you might want to access your AI assistant from your phone or work PC. Deploying to a cloud server is nearly identical, with just a few config tweaks:

bash install-images.sh --prepare-only
## Edit the generated .env file:
## SANDBOX_PROVIDER=box  (or e2b / daytona / createos)
## RAKAZO_HOST=your.domain  (your server domain)
## Add the corresponding sandbox provider API Key
bash install-images.sh

After exposing it to the public internet, it's highly recommended to place an HTTPS reverse proxy in front. The official docs suggest Caddy for its simplicity. Then, in the Electron desktop app or mobile app, select Existing instance and enter your https://your.domain URL.

On first launch, the desktop client will ask whether to "Run Rakazo on this computer" or "Connect to an existing instance". Choose the latter and point it to http://127.0.0.1:5173 if you're running a local dev setup.

Common Issues & Troubleshooting

1. Port 5173 is unreachable after startup

Check container status: docker compose ps. Verify the Web container is Running and port mapping 0.0.0.0:5173 is correct. If containers keep restarting, use docker compose logs to inspect errors.

2. Model connection test fails

Verify three things: ① API Key is correct; ② Model ID format is exact (e.g., openai/gpt-6.1-sol, not just gpt-6.1-sol); ③ Outbound internet access is allowed (cloud VPS firewalls often block outbound port 443 by default).

3. Can't connect to Postgres after changing password in .env

This is a common pitfall. Postgres volumes retain the initial user, password, and database name. Changing POSTGRES_PASSWORD in .env later won't sync to the running database. You either need to docker compose down -v to recreate the volume (⚠️ destroys all data, backup first!) or run ALTER ROLE directly inside the database.

4. Port 5433 is already in use

If another local Postgres instance uses 5433, change POSTGRES_HOST_PORT in .env and update the port in your DATABASE_URL connection string accordingly.

5. Want to develop from source?

For secondary development, the official workflow requires Node.js 22 (22.22.2+), 24.x, or 26+, plus pnpm 9. After cloning, configure .env and run: pnpm install → pnpm db:generate → pnpm db:migrate → pnpm sandbox:build → pnpm dev. This is beyond daily usage; Docker deployment is sufficient for most.

Summary

Let's recap what we just accomplished:

1. Deployed the full Postgres + Web + Worker stack with a single Docker Compose script.
2. Registered an account and connected our own LLM API key, achieving true "model freedom".
3. Created a Persistent Bot to experience AI conversations with long-term memory and context.
4. Learned how to migrate to a cloud server and access the service across desktop and mobile devices.

Rakazo's positioning is clear: it's not a closed corporate product, but an AI Agent you fully control, host yourself, and maintain. In an era of increasingly commercialized AI tools, this self-hosted, controllable approach is increasingly valuable.

Next steps to explore:

• Test voice mode (requires ElevenLabs, OpenAI, or Fish Audio keys)
• Explore app integrations using Composio or Pipedream Connect to plug Rakazo into your workflows
• Configure Bot Routines for automated tasks and notifications
• Review the official Self-hosting Guide for backup and upgrade procedures

The project currently sits at 4400+ Stars and is in Beta. The community is active and growing. If you run into issues during deployment or discover creative use cases, feel free to share them.

Project: elie222/rakazo | One-click Docker deployment, built-in persistent memory, and flexible model support. Get your own AI assistant in under 10 minutes.