Tự host Rakazo trên VPS: bot AI riêng của bạn
Chạy Rakazo trên VPS với Node 22, pnpm, PostgreSQL và Graphile Worker trong Docker Compose; chọn sandbox, quản lý key và tính đúng cấu hình cần dùng.
Rakazo self-host thực sự chạy những gì
Self-host Rakazo có nghĩa là chạy 5 thành phần trên một Linux server: PostgreSQL, một tiến trình Graphile Worker, API, web app và một sandbox container đóng vai trò là máy tính của các bot. Rakazo là một giải pháp thay thế mã nguồn mở cho Grok Bot, do elie222 phát hành theo giấy phép Apache 2.0. Mỗi bot có các cuộc hội thoại, memory, routine và history riêng. Bot dùng chung một Team Computer với các bot khác trong workspace, trừ khi được cấp một Private Computer. Bot cũng có thể tạo các bot ngang hàng hoặc subagent tồn tại trong thời gian ngắn. Nếu các từ như memory, subagent và tool call trong câu trên chưa quen thuộc, hãy tìm hiểu từng bước cách agent thực sự hoạt động trong một buổi chiều trước. Hầu hết các thiết lập bên dưới chỉ có ý nghĩa khi bạn hình dung được bot đang làm gì lúc thức dậy.
Đó là lý do hệ thống này nên chạy trên VPS (virtual private server), không phải trên máy tính để bàn. Bot lưu memory và chạy công việc theo lịch phải có thể truy cập được trong khi bạn ngủ. Laptop chuyển sang chế độ suspend sẽ làm queue dừng lại.
Tính đến tháng 10 năm 2026, Rakazo vẫn tự mô tả là beta, dù hiện đã phát hành các bản release có số phiên bản ổn định. Vì vậy, hãy xem đây là một cấu hình đang vận hành, không phải một appliance hoàn thiện. Toàn bộ stack dùng TypeScript: React 19 và Vite cho web app, Hono cho API, Postgres với Prisma, Better Auth cho tài khoản và Graphile Worker cho các background job. Graphile Worker lưu queue bên trong Postgres, nên không cần chạy Redis hay một data store thứ hai. .env.example đặt WAKEUP_DRIVER=graphile, nghĩa là mỗi lần bot thức dậy sẽ là một job được Postgres hỗ trợ. Khi dừng Postgres, mọi hành động theo lịch của bot cũng dừng theo. Nếu muốn tự lắp ráp một agent từ nhiều thành phần thay vì chạy sản phẩm của người khác, tự xây dựng agent từ các thành phần là hướng còn lại.
Vì sao gói 1 GB không đủ cho hệ thống này
Hãy đếm các process. Postgres là một process. API là một process Node. Worker là process thứ hai. Web app là process thứ ba. Sandbox supervisor là process thứ tư. Sau đó là các máy tính của bot: mặc định có một container Team Computer dùng chung, chứa desktop Linux có giao diện đồ họa, cùng một X display và một process Chrome riêng cho mỗi bot đang hoạt động.
Tài liệu self-host của dự án hiện không còn nêu kích thước máy chủ. Tài liệu tại v0.3.5, được kiểm tra vào ngày 27 October 2026, chỉ liệt kê các yêu cầu phần mềm. Tài liệu có nêu giới hạn cho từng computer: với Docker sandbox, RAKAZO_COMPUTER_MEMORY mặc định là 2g và RAKAZO_COMPUTER_CPUS là 2. Giới hạn này áp dụng cho từng computer, không áp dụng cho từng bot. Mỗi workspace mặc định có một Team Computer, và mọi Team bot đang hoạt động đều chạy desktop cùng browser bên trong computer đó, nên tất cả dùng chung 2 GB và hai core. Chỉ bot được chuyển sang Private Computer mới có container và giới hạn tài nguyên riêng. Khi đặt SANDBOX_PROVIDER=docker, các desktop đó sẽ chạy trên VPS của bạn, bên cạnh control plane, nên 4 GB chỉ là mức tối thiểu chứ không phải mục tiêu. Hãy bắt đầu với 8 GB nếu bạn định giữ nhiều hơn một bot hoạt động, tăng RAKAZO_COMPUTER_MEMORY để computer dùng chung thực sự sử dụng được lượng memory đó, và đo con số thực tế bằng docker stats trong khi các bot làm việc. Browser bên trong sandbox là yếu tố làm tăng mức memory sử dụng, nên bảng thông số sẽ không cho bạn biết con số này. Để ngăn một máy nhỏ chạy quá nhiều browser cùng lúc, hãy đặt SANDBOX_TEAM_SCREEN_LIMIT thành một giá trị dương. Giá trị này giới hạn số desktop đang hoạt động trên Docker Team Computer. 0 mặc định không đặt giới hạn. Nếu tổng memory bị thiếu, RAKAZO_COMPUTER_MEMORY cũng chấp nhận giá trị nhỏ hơn như 1536m. Để biết phương pháp chung khi sizing một máy cho công việc của agent, agent VPS thực sự cần bao nhiêu RAM và CPU trình bày chi tiết cách đo.
Một setting giúp tình trạng này không trở nên tệ hơn. .env.example phát hành với SANDBOX_IDLE_MS=600000, và comment của setting này cho biết computer sẽ được pause hoặc stop sau số mili giây idle đó. Khi idle 10 phút, computer sẽ biến mất. Giá trị tối thiểu được chấp nhận là 30000, còn 0 sẽ tắt chế độ sleep khi idle. Comment tương tự đề xuất dùng 0 cho Docker self-host, vì computer idle không tốn chi phí, nên các app và session chạy lâu vẫn được giữ nguyên. Điều này đúng về chi phí, không đúng về memory. Trên VPS nhỏ, hãy giữ timer này bật, vì nếu không, mọi computer bạn từng khởi động và mọi browser bên trong chúng sẽ tiếp tục chạy.
Disk cũng cần được tính. Sandbox image, các Node module và Postgres volume dùng chung một disk, nên 40 GB là điểm bắt đầu hợp lý.
Ghim phiên bản trước khi clone
Rakazo phát triển nhanh và main không phải là một release. Tính đến ngày 9 November 2026, v0.8.0, được công bố ngày 4 November 2026, là release được đánh dấu Latest. Hướng dẫn này vẫn ghim ở v0.3.5, được công bố ngày 25 October 2026.
git clone https://github.com/elie222/rakazo.git
cd rakazo
git checkout f31e3c0699f086d663637c4107858c238a086fb3
git log -1 --format='%H %ci'Commit đó là commit mà v0.3.5 trỏ tới. Hãy ghim commit thay vì branch hoặc tag. Branch có thể thay đổi sau lần git pull tiếp theo, còn tag là nhãn có thể di chuyển mà maintainer có thể trỏ lại, nên không cái nào xác định một tree mà bạn có thể quay lại. Commit identifier không thể thay đổi. Hãy ghi commit của bạn cùng các thông tin khác về server, vì khi upgrade làm hỏng hệ thống, cách sửa nhanh và rẻ là git checkout <old commit> rồi rebuild; cách này chỉ hiệu quả nếu bạn biết commit nào đang hoạt động. README đã ghim gọi Rakazo là beta, nên việc ghim chính xác phiên bản này đáng với công sức nhỏ bỏ ra. Với project có lịch sử release ổn định và có chủ đích, bạn có thể ghim theo tag đã công bố; một stack self-host nhỏ hơn như openGym làm theo cách đó.
Yêu cầu: Node 22, pnpm 9 và Docker
node -v
pnpm -v
docker --versionpackage.json khai báo "engines": { "node": "^22.22.2 || ^24.0.0 || >=26.0.0" } và "packageManager": "pnpm@9.15.0". Vì vậy, node -v phải in ra v22.22.2 hoặc phiên bản 22.x mới hơn, bất kỳ v24 nào, hoặc v26 trở lên. v22 cũ hơn 22.22.2 nằm ngoài phạm vi này, và README nêu rõ rằng Node.js 23.x và 25.x không được hỗ trợ. Cài một phiên bản Node được hỗ trợ từ NodeSource hoặc nvm. Corepack đi kèm Node 22 và 24; với Node 26 trở lên, trước tiên hãy cài Corepack bằng npm install -g corepack. Sau đó kích hoạt pnpm:
corepack enable
corepack prepare pnpm@9.15.0 --activateDocker Engine cùng compose plugin đáp ứng các yêu cầu còn lại. Tài liệu tự host yêu cầu Docker Engine 26 trở lên và API 1.45 trở lên để dùng các volume subpath cho bot, cùng với curl và OpenSSL. User của bạn cũng phải có quyền truy cập daemon. Nếu docker ps trả về permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock, hãy thêm user của bạn vào group docker rồi mở một login shell mới. Trước tiên cần hiểu quyền được cấp: là thành viên của docker tương đương với root trên máy, vì bất kỳ ai trong group đó cũng có thể khởi động một container mount filesystem của host.
Cấu hình .env, sau đó khởi động Postgres
cp .env.example .env
chmod 600 .envCần thay đổi một số giá trị trước khi khởi động bất kỳ thành phần nào. .env.example cung cấp sẵn 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 và SANDBOX_SUPERVISOR_TOKEN=replace-with-32-plus-character-supervisor-token, đồng thời để trống POSTGRES_PASSWORD và POSTGRES_APP_PASSWORD. Tất cả placeholder này đều được công khai trong repository. Vì vậy, một bản deploy vẫn giữ nguyên bất kỳ placeholder nào sẽ chạy với một secret mà ai cũng có thể đọc. Tạo một giá trị ngẫu nhiên riêng cho từng placeholder. ENCRYPTION_KEY phải có 64 ký tự hex ngẫu nhiên. Đó chính xác là giá trị mà openssl rand -hex 32 in ra. Các secret còn lại cần ít nhất 32 ký tự, nên chạy dòng base64 một lần cho từng secret. Tài liệu self-host yêu cầu hai password Postgres dùng giá trị an toàn cho URL. Dòng cuối cùng sẽ tạo các giá trị đó, nên cũng chạy nó một lần cho mỗi password. Database có hai tài khoản đăng nhập. DATABASE_MIGRATION_URL được cung cấp sẵn dưới dạng postgres://rakazo:REPLACE_WITH_POSTGRES_PASSWORD@127.0.0.1:5433/rakazo. Đây là tài khoản owner dùng để chạy migration. DATABASE_URL được cung cấp dưới dạng postgres://rakazo_app:REPLACE_WITH_POSTGRES_APP_PASSWORD@127.0.0.1:5433/rakazo. Đây là tài khoản riêng của app, không có quyền superuser và chịu row-level security. Đặt từng password vào URL riêng. pnpm db:migrate tạo tài khoản rakazo_app với password bạn đã đặt.
openssl rand -base64 48
openssl rand -hex 32
openssl rand -hex 24Sau đó chỉ khởi động database và chạy migration.
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 build image máy tính cho bot. Image này được định nghĩa trong package.json dưới dạng docker build -t rakazo/computer:local infra/sandboxes/computer. Đây là graphical image, nên lần build đầu tiên sẽ tải nhiều dữ liệu và mất thời gian. Xác nhận image đã được tạo bằng docker image ls rakazo/computer. Lệnh này phải in ra một dòng.
File compose cơ sở không publish cổng Postgres nào. Overlay docker-compose.postgres-host.yml trong lệnh đó publish cổng này dưới dạng 127.0.0.1:5433, chỉ bind trên loopback, để các tool chạy trên host như pnpm db:migrate và pnpm dev có thể kết nối. Giữ nguyên cấu hình đó. Compose sẽ từ chối khởi động Postgres nếu không có POSTGRES_PASSWORD trong .env, nhưng một cổng Postgres có thể truy cập từ Internet sẽ tạo điều kiện cho các cuộc tấn công dò password. File compose production đọc cùng biến đó và không publish cổng database.
Lần chạy đầu tiên
pnpm devLệnh này khởi động 4 thành phần: API trên port 3100, Graphile Worker, web app Vite trên port 5173 và sandbox supervisor trên port 7091 theo mặc định. Nếu các port đó đang được sử dụng, pnpm dev sẽ chọn một block port còn trống và in ra các URL. Với các port mặc định, app có tại http://127.0.0.1:5173 và bạn sẽ thấy trang đăng nhập.
Trên VPS, bạn không ngồi trực tiếp tại máy đó và không nên publish port 5173 để truy cập. Thay vào đó, hãy forward port qua SSH (secure shell) từ máy của bạn.
ssh -L 5173:127.0.0.1:5173 -L 3100:127.0.0.1:3100 you@your-serverHãy chú ý sự khác nhau giữa các cách chạy này. pnpm dev chạy Vite trên host và chỉ bind cục bộ. Service web trong file compose development publish 127.0.0.1:5173:5173, còn service api của nó 127.0.0.1:3100:3100, cả hai chỉ bind trên loopback, nên cùng một tunnel có thể dùng cho cách này. Trong file production, web app không publish host port nào mà chỉ expose port 5173 cho các container trên network riêng của nó. Chỉ Caddy publish port 80 và 443. Vì vậy, với mọi thứ bạn để chạy lâu dài, hãy dùng file production và reverse proxy của file đó.
Máy chủ nào an toàn để chạy sandbox?
Đây là thiết lập cần cấu hình đúng. SANDBOX_PROVIDER trong .env là docker theo mặc định, và checkout đã pin cũng hỗ trợ Railway bên cạnh các provider được liệt kê trong tài liệu self-host.
dockerlà mặc định. Máy tính của bot chạy dưới dạng container trên máy của bạn, được tạo từ imagepnpm sandbox:buildsản xuất và chạy dưới một supervisor. Theo mặc định, các bot trong một workspace dùng chung một Team Computer. Bot chỉ có container riêng khi chạy trên Private Computer. Không cần tài khoản E2B.e2bchạy các máy tính của bot trên E2B và cầnE2B_API_KEY. Tạiv0.3.5, factory chấp nhận provider này trong production khi có key, không có giới hạnNODE_ENV. Tài liệu self-host gọi đây là lựa chọn phù hợp cho production public hoặc multi-user, vì các máy tính của bot được tách khỏi host chạy API và database của bạn.daytona,createosvàboatlà các provider remote khác. Mỗi provider cần key riêng:DAYTONA_API_KEY,CREATEOS_SANDBOX_API_KEYhoặcBOAT_API_KEY.railwaychạy máy tính trên Railway và cầnRAILWAY_API_TOKENcùngRAILWAY_ENVIRONMENT_IDđược chọn rõ ràng trên API và worker. Dùng một project hoặc environment Railway riêng cho sandbox.desktopchạy trực tiếp các lệnh của bot trên host chạy API và worker, đúng như tài liệu mô tả. Tạiv0.3.5, API và worker từ chối provider này trừ khiNODE_ENVlàdevelopmenthoặctest. Tuy nhiên,.env.examplephát hành kèmNODE_ENV=development, nên server chạypnpm devvẫn chấp nhận provider này. Không bật provider này trên service public hoặc dùng chung.fakechỉ là emulator để verification. Đây không phải runtime.nonekhởi động product mà không cần computer host.
Hãy hiểu đúng theo nghĩa đen. Trong desktop mode hoàn toàn không có ranh giới isolation. Bot chạy shell command bằng user đang chạy API process, cùng home directory, SSH key, cloud credential và .env của user đó. Nội dung trên web page mà bot đọc có thể trở thành command trên server của bạn. Chạy desktop mode trên server là cách khiến bot nắm được credential của bạn. Chỉ dùng mode này trên máy bạn trực tiếp sử dụng, hoặc không dùng. Chuyển provider sẽ đặt một container quanh đường đi qua web page đó thay vì đóng đường đi này. Cấp cho bot một backend tìm kiếm SearXNG riêng cũng xử lý cùng bề mặt tấn công injection từ phía search.
docker tạo ranh giới thực sự giữa bot và host, nhưng ranh giới giữa các bot với nhau còn yếu. Theo mặc định, các bot dùng chung một Team Computer. Tài liệu về computer runtime cho biết các Team bot dùng chung OS user, workspace, browser profile, shell và quyền truy cập X11. Tài liệu cũng nói rõ các thư mục riêng của từng bot chỉ dùng để tổ chức công việc, không phải security boundary. Vì vậy, bất kỳ Team bot nào cũng có thể đọc file của Team bot khác. Bot cần có vùng tách biệt riêng phải chạy trên Private Computer. Docker provider chạy mỗi Private Computer dưới dạng một sibling container riêng trên network riêng. Tuy nhiên, supervisor tạo các container đó mount /var/run/docker.sock. Tài liệu self-host nêu rõ: truy cập socket này tương đương với quyền kiểm soát Docker host. Vì vậy, hãy giữ supervisor ở chế độ private. .env.example coi SANDBOX_SUPERVISOR_TOKEN là credential riêng, khác với BETTER_AUTH_SECRET. Docker sandbox cần credential này ngoài môi trường local development. Product được phát hành kèm một placeholder mà bất kỳ ai cũng có thể đọc trên GitHub. Hãy cấp cho nó một giá trị ngẫu nhiên riêng. Để có mức tách biệt mạnh nhất trong các lựa chọn hiện có, dùng e2b, hoặc cấp cho Rakazo một máy không chứa dữ liệu hay service nào khác. Đây cũng là lý do nên chạy coding agent trong một VM dùng một lần: cách rẻ nhất để giảm hậu quả khi agent làm sai là dùng một máy không có giá trị gì.
Khóa API của model được lưu ở đâu?
Tính năng tính phí theo credit của model trong Rakazo vẫn tắt trừ khi cả hai secret của Stripe đều được thiết lập. Bạn tự cung cấp key. .env.example thiết lập PI_DEFAULT_PROVIDER=openrouter, nên OPENROUTER_API_KEY là nơi thường dùng, và key của các provider cũng hoạt động qua cùng setting này.
Giữ key trong .env và không đưa nó vào bất kỳ file nào được commit. Cả hai lệnh compose trong repository đều truyền --env-file .env, nên các giá trị được chuyển vào container mà không bao giờ được ghi vào YAML do git theo dõi. Bạn cũng có thể để trống OPENROUTER_API_KEY rồi kết nối model trong app sau khi đăng ký. Đây là một lý do nữa để ENCRYPTION_KEY phải có giá trị ngẫu nhiên thực sự thay vì placeholder đi kèm.
Hãy đặt spending limit cho key tại provider trước khi bot sử dụng nó. Bot bị lặp cũng là bot tiêu tiền. Rakazo cũng cung cấp MAX_TOOL_CALLS_PER_TURN: đặt một số nguyên dương để dừng mềm một lượt khi lượt đó vượt quá ngân sách gọi tool, đồng thời vẫn tạo message cuối cùng từ assistant. Khi không đặt, để trống hoặc đặt 0, giới hạn sẽ không được áp dụng. Giá trị này đếm số lần gọi tool, không đếm tiền, nên không thay thế spending limit của provider. Đặt tên riêng cho key này để bạn có thể revoke riêng nó. Nếu bạn thiết lập cho một team thay vì cho chính mình, một gateway của OneCLI đứng trước agent của mọi người là một cách giải quyết khác cho cùng vấn đề, vì provider key được giữ ở một nơi thay vì mỗi người giữ một key.
Từ chế độ phát triển sang cấu hình có thể chạy lâu dài
Repository cung cấp một file Compose dành cho production. File này chạy Postgres, API, worker, web app và Caddy để tự động lấy chứng chỉ TLS (bảo mật tầng truyền tải). Caddy là service duy nhất trong file này publish port. Theo mặc định, file dùng E2B cho các máy tính của bot. Overlay tùy chọn infra/compose/docker-compose.prod.docker.yml thay thế bằng các máy tính Docker cục bộ trên cùng stack. Tài liệu cảnh báo supervisor mà overlay này thêm vào có quyền tương đương root trên 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/healthTạo tài khoản deploy chỉ đăng nhập bằng key và xác nhận bạn có thể đăng nhập bằng tài khoản đó trước khi chạy script. harden-host.sh tắt đăng nhập SSH bằng password và bằng root, giới hạn rate SSH, thêm các rule cho SSH, HTTP và HTTPS qua UFW (tường lửa không phức tạp), đồng thời giữ nguyên các rule mạng riêng hiện có. Script cũng bật fail2ban, unattended security updates, AppArmor và các audit rule. Script từ chối chạy nếu không có SSH_CONNECTION. Vì vậy, command truyền giá trị này qua sudo. Script sẽ rollback thay đổi firewall nếu bạn không xác nhận thay đổi đó từ một SSH session mới trong vòng ba phút. Hãy đọc script trước khi chạy vì script thay đổi cách bạn đăng nhập và reload SSH. Giữ console của nhà cung cấp mở cho đến khi đăng nhập SSH mới thành công.
Production .env cần nhiều thành phần hơn bản development. Tài liệu self-host liệt kê các yêu cầu tối thiểu sau, cùng với các secret.
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>Trỏ một bản ghi A đến server trước lần up đầu tiên. Caddy yêu cầu chứng chỉ cho tên trong RAKAZO_HOST. Tên này phải phân giải đến server này. Ngoài ra, port 80 để xác thực HTTP hoặc port 443 để xác thực TLS-ALPN phải truy cập được từ bên ngoài. Cả hai challenge đều được bật theo mặc định. Vì vậy, chỉ đóng port 80 không ngăn được việc cấp chứng chỉ qua port 443.
Ngay từ đầu, hãy đặt SIGNUP_ALLOWLIST thành địa chỉ của bạn. .env.example cung cấp SIGNUPS_ENABLED=true. Cả hai setting đều được đọc từ environment mỗi khi API khởi động. Vì vậy, một instance dùng public name, bật signup nhưng không có allowlist sẽ nhận đăng ký từ bất kỳ ai tìm thấy nó. Allowlist không rỗng được áp dụng ở mỗi lần khởi động và thay thế danh sách đã lưu. Signup có allowlist yêu cầu xác minh mailbox, bao gồm cả tài khoản đầu tiên. Vì vậy, hãy thiết lập email delivery trước khi đăng ký. Nếu không có email, tài liệu hướng dẫn bắt đầu với SIGNUPS_ENABLED=false rồi tạo tài khoản bằng bootstrap command phía server được cung cấp. Cách này tạo một tài khoản đã xác minh thông thường, không có quyền trên server. Hãy đặt allowlist trước. Sau đó có thể nới lỏng nếu cần. Nếu bạn đã chạy nhiều service trên cùng server và muốn dùng một danh sách người dùng chung thay vì một allowlist cho từng app, đặt một instance Authentik ở phía trước chúng sẽ chuyển quyết định này sang proxy. Tuy nhiên, Authentik nằm trước các tài khoản Better Auth riêng của Rakazo chứ không thay thế chúng.
Hãy coi docs/self-host.md trong repository là nguồn chính xác cho các setting production vì file này thay đổi cùng code còn hướng dẫn này thì không. Vì Compose thực hiện toàn bộ công việc, các quy tắc thông thường vẫn áp dụng. Phần hướng dẫn cơ bản về Docker Compose cho VPS giải thích vì sao --env-file và named volume trở nên quan trọng hơn khi một stack được để chạy trong nhiều tháng.
Bản sao lưu
Postgres và thư mục data/ chứa dữ liệu của instance trong thiết lập này. Để khôi phục, bạn cũng cần ENCRYPTION_KEY và mọi content master key đã cấu hình, vì vậy hãy lưu bản sao bên ngoài server.
./scripts/backup.sh
./scripts/restore.sh backups/BACKUP_TIMESTAMPbackup.sh dump Postgres và archive data/. restore.sh hoạt động trên Compose stack dùng cho development, với một database trống và các application service đã dừng; nó không đọc các file backup production. Với máy chủ quan trọng, hãy cài infra/compose/backup-prod.sh dưới dạng /usr/local/sbin/rakazo-backup cùng với timer do repository cung cấp. Công cụ này ghi một dump đã xác minh và một archive dữ liệu ứng dụng vào /var/backups/rakazo, mặc định giữ tối đa 3 snapshot đã xác minh theo giá trị RAKAZO_BACKUP_KEEP, trong giới hạn 50 GiB do RAKAZO_BACKUP_MAX_GB đặt. Trước mỗi lần chạy, nó xóa các snapshot chưa hoàn tất và lịch sử vượt quá giới hạn, nên việc xoay vòng được tự động thực hiện. Công cụ cũng có thể mã hóa từng backup bằng age cho các public recipient được liệt kê trong /etc/rakazo/backup.env, để server ghi các backup mà chính nó không thể đọc. Hãy tạo cặp key đó trên một máy bạn kiểm soát và giữ private key bên ngoài server. Nếu không có recipient, backup vẫn ở dạng plaintext và công cụ ghi cảnh báo. Tuy nhiên, sau backup được mã hóa đầu tiên, lần chạy không có recipient sẽ thất bại trừ khi bạn cho phép plaintext một cách rõ ràng bằng RAKAZO_BACKUP_ALLOW_PLAINTEXT=1. Backup nằm trên cùng disk với database không phải là backup, vì vậy hãy sao chép nó ra khỏi máy chủ. Sau đó hãy khôi phục thử một lần trên server dự phòng trước khi bạn thực sự cần đến nó.
Nguyên nhân lỗi và những gì bạn sẽ thấy
pnpm db:migrate không thể kết nối đến database. Migration báo rằng nó không thể kết nối đến database server tại 127.0.0.1:5433. Có thể container Postgres chưa chạy, đã chạy nhưng chưa sẵn sàng, hoặc được khởi động mà không có overlay docker-compose.postgres-host.yml, vốn dùng để publish cổng 5433 ra host. Chạy docker compose --env-file .env -f infra/compose/docker-compose.yml ps và tìm service postgres có trạng thái healthy, vì compose file cấu hình health check chạy mỗi ba giây. Nếu container restart liên tục, hãy đọc log của nó: Compose stack được pin version sẽ từ chối khởi động trên volume Postgres 16 cũ cho đến khi volume đó được migrate sang Postgres 18. docker compose ... down -v sẽ xóa volume này, đồng thời xóa luôn dữ liệu trong đó.
Cổng đã bị chiếm. Khởi động Postgres sẽ fail với bind: address already in use nếu có tiến trình khác đang giữ cổng 5433, thường là một Rakazo stack cũ mà bạn quên stop. sudo ss -lntp | grep 5433 cho biết tiến trình đó. Overlay đọc cổng trên host từ POSTGRES_HOST_PORT, nên bạn có thể đổi cổng này, miễn là đổi cả DATABASE_URL và DATABASE_MIGRATION_URL theo.
Bot không bao giờ được cấp computer. Khi có SANDBOX_PROVIDER=docker nhưng không có image rakazo/computer:local thì không có gì để khởi động. docker image ls rakazo/computer trả lời vấn đề đó trong một dòng, còn pnpm sandbox:build sẽ sửa lỗi. Nếu supervisor không thể truy cập Docker socket thì cũng không thể tạo container, và thông báo lỗi sẽ nêu đường dẫn: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock.
Lệnh chạy lâu bị dừng giữa chừng. .env.example đặt SANDBOX_COMMAND_TIMEOUT_MS=300000, vì vậy một lệnh duy nhất bên trong computer của bot sẽ bị dừng sau năm phút. Hãy tăng giá trị này cho các build chậm, thay vì cho rằng sandbox đã bị crash.
pnpm install bị lỗi theo cách khó hiểu. Trước tiên hãy kiểm tra node -v. Workspace khai báo ^22.22.2 || ^24.0.0 || >=26.0.0, nên 23.x, 25.x và mọi phiên bản 22.x trước 22.22.2 đều không được hỗ trợ. .npmrc được pin version và đặt engine-strict=true, nên pnpm install sẽ từ chối phiên bản Node không được hỗ trợ bằng lỗi engine/version trước khi code dependency của ứng dụng chạy.
Đăng nhập hoạt động cục bộ nhưng không hoạt động qua domain. BETTER_AUTH_URL, WEB_ORIGIN và API_URL đều phải dùng cùng public origin với thanh địa chỉ, bao gồm cả scheme. Một http://127.0.0.1:5173 cũ còn sót lại trong một trong các giá trị này là nguyên nhân thường gặp khiến session không bao giờ được duy trì.
Cập nhật checkout đã pin
Quy trình nâng cấp trong tài liệu self-host cho một stack Compose production được dựng từ checkout khá ngắn: pull source mới, sau đó rebuild và restart API, worker và web app. Migration chạy khi API khởi động, vì lệnh start của nó áp dụng migration trước khi phục vụ request.
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 webHãy backup trước. Migration chỉ tiến về phía trước, còn beta không cho bạn một đường quay lui đáng tin cậy. Nếu checkout của bạn cũ hơn ngày 30 August 2026, bao gồm cả commit v0.1.0-beta, hãy đọc ghi chú trong tài liệu về migration 20260830200000_space_scope_names_and_user_credentials trước khi nâng cấp. Đây là một lần chuyển đổi cần phối hợp, vì vậy trước tiên hãy stop API và worker cũ rồi chạy kiểm tra privacy boundary của Space theo hướng dẫn trong tài liệu. Khi nâng cấp từ checkout có trước thời điểm tách riêng đăng nhập app, hãy đặt POSTGRES_APP_PASSWORD trong .env trước khi rebuild; file Compose production sẽ từ chối khởi động nếu thiếu biến này. Các file Compose cho source-checkout và production cũng chạy Postgres 18: một cài đặt Postgres 16 hiện có cần thực hiện quy trình infra/compose/upgrade-postgres.sh trong tài liệu trước khi có thể khởi động với layout mới. Hãy đọc các commit nằm giữa SHA đã pin và SHA mới trước khi áp dụng, vì một project còn mới như vậy có thể đổi tên biến môi trường mà không thông báo, và biến bị thiếu thường khiến service khởi động rồi thoát. Nếu bạn vẫn đang cân nhắc Rakazo có phù hợp để chạy hay không, bài tổng hợp về các AI agent self-host trình bày những lựa chọn khác trong nhóm này và chi phí duy trì từng lựa chọn.
FAQ
Tôi có thể chạy Rakazo trên VPS 1 GB không?
Không. Postgres, API, worker, sandbox supervisor và web app đều chạy đồng thời. Khi dùng SANDBOX_PROVIDER=docker, máy tính của bot còn thêm một container chứa desktop đồ họa, với một X display riêng và một process Chrome riêng cho mỗi bot đang hoạt động. Tất cả cùng nằm trong giới hạn mặc định là 2 GB memory và 2 CPU. Tài liệu self-host tại v0.3.5 không nêu cấu hình host. Hãy xem 4 GB là mức tối thiểu cho control plane và dùng cấu hình cao hơn khi desktop chạy trên máy của bạn.
Desktop sandbox provider có an toàn trên server không?
Không. Tài liệu self-host cho biết desktop chạy command trực tiếp trên API và worker host. Vì vậy, bot hoạt động với quyền của user đang chạy process đó và có thể truy cập các file cũng như credential của user này. Trong v0.3.5, API và worker từ chối provider này ngoài development và test mode. Tuy nhiên, server chạy pnpm dev đang ở development mode và sẽ chấp nhận provider đó. Không bật provider này trên server public hoặc server dùng chung. Hãy dùng docker để cấp cho bot một Private Computer khi bot không được chia sẻ file với các bot khác trong workspace, hoặc dùng e2b khi có nhiều người đăng nhập.
Tôi nên cài phiên bản Rakazo nào?
Tính đến ngày 9 November 2026, release mới nhất là v0.8.0, được công bố ngày 4 November 2026 và đánh dấu Latest. Để làm theo hướng dẫn này, hãy checkout commit v0.3.5 đã được ghim, tức f31e3c0699f086d663637c4107858c238a086fb3, thay vì theo dõi main hoặc prerelease tháng August là v0.1.0-beta. Branch có thể thay đổi sau đó và tag có thể bị trỏ lại, nên không cái nào xác định một tree mà bạn có thể quay lại. Hãy ghi lại commit, vì chỉ có thể rollback khi bạn biết commit nào đã hoạt động.
Tôi đặt OpenRouter API key ở đâu?
Đặt trong .env với giá trị OPENROUTER_API_KEY, và không bao giờ đặt trong compose file mà bạn commit. Cả hai compose command trong repository đều truyền --env-file .env, nên giá trị này đến được các container mà không bị ghi vào YAML được theo dõi trong repository. Bạn cũng có thể để trống rồi connect model trong app sau khi signup. Hãy đặt spending limit cho key tại provider, vì bot bị lặp có thể tiếp tục gọi model cho đến khi có thứ gì đó dừng nó.
Tôi có cần domain name và TLS không?
Có, nếu dùng ngoài lần test đầu tiên. Production compose file chạy Caddy và tự động lấy certificate. Hãy đặt RAKAZO_HOST thành public hostname, đồng thời đặt BETTER_AUTH_URL, WEB_ORIGIN và API_URL thành cùng một public HTTPS origin. Để xem thử lần đầu, bạn có thể bỏ qua domain: chạy pnpm dev rồi forward port 5173 qua SSH thay vì publish port này.