Rakazo 自行託管：VPS 部署與硬體需求

Rakazo 自行託管實際執行的內容

自行託管 Rakazo，表示在一台 Linux 伺服器上執行五個元件：PostgreSQL、Graphile Worker 程序、API、Web 應用程式，以及每個目前啟用的 bot 各自使用的一個 sandbox 容器。Rakazo 是 Grok Bot 的開放原始碼替代方案，由 elie222 以 Apache 2.0 授權條款發布。每個 bot 都有自己的執行緒、電腦、記憶與歷史記錄，也能啟動同儕 bot 或生命週期短暫的 subagent。

這也是為什麼 Rakazo 應部署在 VPS（virtual private server），而不是桌上型電腦上。保存記憶並執行排程工作的 bot，必須在你休息時仍能連線。筆記型電腦進入暫停狀態後，佇列就會停止處理。

截至 2026 年 8 月，Rakazo 仍處於 early beta，因此應將以下內容視為可運作的設定，而不是完成品。整個技術堆疊都使用 TypeScript：Web 應用程式使用 React 19 和 Vite，API 使用 Hono，資料庫使用搭配 Prisma 的 Postgres，帳戶功能使用 Better Auth，背景工作則使用 Graphile Worker。Graphile Worker 將佇列儲存在 Postgres 內，因此不需要執行 Redis，也不需要額外的資料儲存服務。.env.example 設定 WAKEUP_DRIVER=graphile，因此 bot 的喚醒動作就是由 Postgres 支援的工作。停止 Postgres 後，所有排程中的 bot 動作都會停止。如果你想自行組合 agent，而不是執行他人開發的產品，另一條路徑是使用元件自行建立 agent。

為什麼 1 GB 方案無法支撐這套配置

先計算程序數量。Postgres 是一個。API 是一個 Node 程序。worker 是第二個。Web 應用程式是第三個。sandbox supervisor 是第四個。接著，每個執行中的 bot 都會使用一個包含圖形化 Linux 桌面和瀏覽器的容器。

專案自己的自架文件提供了一個誠實的數字：當 E2B 負責 bot 桌面時，2 vCPU 和 4 GB 的機器足以執行 API、worker 與 Postgres。這個數字只適用於控制平面，因為高負載部分是由其他地方代管。設定 SANDBOX_PROVIDER=docker 後，這些桌面會移到你的 VPS，因此 4 GB 會變成最低需求，而不是建議目標。如果你計畫讓不只一個 bot 保持執行，請從 8 GB 開始，並在 bot 工作期間使用 docker stats 測量實際用量。sandbox 內的瀏覽器會大幅影響記憶體用量，因此僅看規格表無法得出準確數字。若要了解為 agent 工作配置伺服器的一般方法，agent VPS 實際需要多少 RAM 與 CPU會詳細說明測量方式。

有一項設定可以避免情況惡化。.env.example 會隨附 SANDBOX_IDLE_MS=600000，並附有註解說明：經過指定的閒置毫秒數後，暫停 E2B 電腦，或停止 Docker 電腦。閒置 10 分鐘後，電腦就會被釋放。接受的最小值是 30000。沒有這項設定，你曾開啟的每個 bot 都會永久占用記憶體。

磁碟空間也要計算在內。sandbox 映像檔、Node 模組和 Postgres volume 共用同一個磁碟，因此 40 GB 是合理的起始值。

複製前固定版本

Rakazo 的變更速度很快，而 main 並不是正式版本。截至 16 August 2026，該儲存庫只有 1 個標籤：v0.1.0-beta。此標籤於 13 August 2026 發布，並標記為預發布版本。

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

v0.1.0-beta 指向的就是該 commit。請固定 commit，不要固定分支或標籤。分支會在下一次 git pull 時變更；標籤則是可移動的名稱，維護者可以重新指定其指向。因此，兩者都無法識別可供還原的特定樹狀目錄。commit 識別碼不會變更。請將它與其他伺服器資訊記錄在一起。升級造成問題時，最簡單的修復方式是 git checkout <old commit> 並重新建置；但這只有在你知道哪個 commit 曾正常運作時才有效。

需求：Node 22、pnpm 9 與 Docker

node -v
pnpm -v
docker --version

package.json 宣告 "engines": { "node": ">=22" } 與 "packageManager": "pnpm@9.15.0"，因此 node -v 必須輸出 v22 或更高版本。Ubuntu 套件庫中的 Node 套件通常較舊，因此請從 NodeSource 或 nvm 安裝。pnpm 會透過 corepack 隨 Node 提供：

corepack enable
corepack prepare pnpm@9.15.0 --activate

Docker Engine 加上 compose plugin 即可涵蓋其餘需求，而且您的使用者必須能夠存取 daemon。若 docker ps 回應 permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock，請將您的使用者加入 docker 群組，然後開啟新的登入 shell。請先了解這項權限的影響：加入 docker 等同於取得該機器的 root 權限，因為該群組中的任何人都能啟動掛載主機檔案系統的容器。

設定 .env，然後啟動 Postgres

cp .env.example .env
chmod 600 .env

在任何服務連接網路前，必須先變更兩個值。.env.example 會附帶 BETTER_AUTH_SECRET=replace-with-32-plus-character-secret 和 ENCRYPTION_KEY=replace-with-64-char-hex-or-passphrase。Rakazo 在開發環境以外會拒絕這些預留位置值，因此設定不完整的部署會直接失敗，不會使用已發佈在儲存庫中的 secret 執行。

openssl rand -base64 48
openssl rand -hex 32

接著單獨啟動資料庫，並執行 migration。

docker compose --env-file .env -f infra/compose/docker-compose.yml up postgres -d
pnpm install
pnpm db:generate
pnpm db:migrate
pnpm sandbox:build

pnpm sandbox:build 會建置 bot 的電腦影像，該影像在 package.json 中定義為 docker build -t rakazo/computer:local infra/sandboxes/computer。這是圖形影像，因此第一次建置會下載大量內容並需要一些時間。使用 docker image ls rakazo/computer 確認影像已建置完成；該指令應輸出一列。

compose 檔案會將 Postgres 發佈為 127.0.0.1:5433:5432，且僅繫結至 loopback。請維持此設定。開發環境的認證資訊為 rakazo:rakazo，而且已存在於儲存庫中；如果 Postgres 埠使用已公開的密碼對網際網路開放，通常幾小時內就會被掃描器發現。正式環境的 compose 檔案則會改讀 POSTGRES_PASSWORD，到達該步驟時請將它設為隨機字串。

第一次執行

pnpm dev

這會啟動 4 個項目：監聽 3100 埠的 API、Graphile Worker、監聽 5173 埠的 Vite web app，以及監聽 7091 埠的 sandbox supervisor。應用程式位於 http://127.0.0.1:5173，此時應會看到登入頁面。

在 VPS 上，您不會直接操作該主機，也不應公開發布 5173 埠來存取應用程式。請改用 SSH（secure shell）從自己的電腦轉送連接埠。

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

請注意這兩種執行方式的差異。pnpm dev 會在主機上執行 Vite，且僅繫結至本機。compose 檔案中的 web 服務會將 5173:5173 發布到所有網路介面。在公開 VPS 上啟動完整的開發 compose stack 會使應用程式暴露，因此對於要持續執行的服務，請使用 production 檔案及其 reverse proxy。

伺服器上哪種 sandbox provider 安全？

這是最需要設定正確的一項。SANDBOX_PROVIDER 在 .env 中接受 4 個值。

• docker 是預設值。每個 bot 都會在你的機器上取得自己的 container，並使用產生的 image pnpm sandbox:build 建立。這是最快的自架設定。
• e2b 會在 E2B 上執行 bot computer，並需要 E2B_API_KEY。專案建議公開或多使用者部署採用此設定，因為它能將 bot computer 與執行 API 和資料庫的主機分隔開來。
• desktop 會直接在 API 和 worker 主機上執行 bot 的命令。儲存庫中的指示十分明確：不要在公開或共用伺服器上使用。
• fake 是供測試使用的程序內 emulator，不是執行環境。

請確實按照桌面模式的警告處理。在桌面模式中完全沒有隔離邊界，因此 bot 會以執行 API process 的使用者身分執行 shell 命令，並取得該使用者的 home directory、SSH keys、cloud credentials 以及該使用者的 .env。bot 讀取的網頁文字可能會變成你伺服器上的命令。在伺服器上使用 desktop mode，可能導致 bot 取得你的 credentials。請只在你能直接操作的機器上使用，否則不要使用。

docker 是實際存在但不完善的隔離邊界。由於每個 bot 都有自己的 container，一個 bot 無法讀取另一個 bot 的檔案。不過，建立這些 container 的 supervisor 會掛載 /var/run/docker.sock，而控制主機 Docker socket 就等同於控制主機。因此，請讓 supervisor 僅供內部使用。.env.example 將 SANDBOX_SUPERVISOR_TOKEN 文件為選用的獨立服務 credential；若該值為空，預設為 BETTER_AUTH_SECRET。這表示若將該 secret 保留為 placeholder，建立 container 的服務就會受到 GitHub 上任何人都能讀取的字串保護。請設定這兩個值。若要使用這裡可提供的最強隔離，請使用 e2b，或提供一台不存放其他資料的機器給 Rakazo。這也是 在一次性 VM 中執行 coding agents 背後的相同理由：agent 出錯時，最便宜的應對方式就是讓它使用的機器沒有任何價值。

模型 API 金鑰應放在哪裡？

Rakazo 不提供代管模型計費功能。您必須自行提供金鑰。.env.example 會設定 PI_DEFAULT_PROVIDER=openrouter，因此 OPENROUTER_API_KEY 是通常使用的位置，且各家供應商的金鑰都透過相同設定運作。

請將金鑰保存在 .env，不要放入任何會提交的檔案。儲存庫中的兩個 compose 命令都會傳遞 --env-file .env，因此值會傳入容器，不會寫入由 git 追蹤的 YAML。您也可以將 OPENROUTER_API_KEY 留空，並在初始設定期間於應用程式中貼上金鑰。這也是 ENCRYPTION_KEY 必須使用真正的隨機值，而不是隨附預留值的另一個原因。

在 bot 使用金鑰前，先向供應商為該金鑰設定支出上限。持續迴圈的 bot 會持續產生費用，而每個金鑰的上限是唯一不依賴您監看的停止機制。為這個金鑰設定專用名稱，方便單獨撤銷。

從開發模式轉換為可持續執行的環境

此 repository 提供 production compose file，會執行 Postgres、API、worker、web app，以及自動申請 TLS（transport layer security）憑證的 Caddy。它需要 E2B 提供 bot computers。

sudo DEPLOY_USER=deploy bash infra/compose/harden-host.sh
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml up -d --build

harden-host.sh 會停用 SSH 密碼登入、設定 SSH、HTTP 與 HTTPS 的 UFW（uncomplicated firewall）規則、啟用 fail2ban，並套用 AppArmor profiles。執行前請先閱讀，因為它會變更登入方式。執行期間請保持第二個 SSH 工作階段開啟。

production .env 比 development 的設定需要更多項目。self-host 文件列出以下最低需求。

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
POSTGRES_PASSWORD=<random>
BETTER_AUTH_SECRET=<random>
ENCRYPTION_KEY=<random>
E2B_API_KEY=<your key>
OPENROUTER_API_KEY=<your key>
SANDBOX_PROVIDER=e2b
AGENT_RUNTIME=pi
DATA_DIR=/data

在第一次執行 up 前，先將 A record 指向該伺服器。Caddy 會為 RAKAZO_HOST 中的名稱申請憑證。如果該名稱未解析至此主機，或對外關閉 port 80，申請就會失敗。

此外，請設定 SIGNUP_ALLOWLIST=you@example.com。SIGNUPS_ENABLED=true 的預設值會讓公開名稱上的 instance 接受任何找到它的人註冊，而每個新帳戶都會取得一台 computer。請先設定 allowlist。之後如有需要，再放寬限制。

請將 repository 中的 docs/self-host.md 視為 production 設定的依據，因為它會隨程式碼變更，而本指南不會同步更新。由於實際工作由 Compose 負責，通常的規則仍然適用；VPS 的 Docker Compose 基礎說明了為何當 stack 需要連續數月無人介入時，--env-file 與 named volumes 會更加重要。

備份

Postgres 與 data/ 目錄構成完整的執行個體。

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

backup.sh 會傾印 Postgres，並封存 data/。對於需要依賴的機器，請依照儲存庫提供的 timer，將 infra/compose/backup-prod.sh 安裝為 /usr/local/sbin/rakazo-backup，讓系統自動執行備份輪替。備份若與資料庫位於同一顆磁碟上，就不算備份，因此請將備份複製到其他主機。接著在真正需要還原之前，先於備用伺服器上還原一次。

失敗原因與可看到的現象

pnpm db:migrate 無法連線至資料庫。 Migration 顯示無法連線至 127.0.0.1:5433 的資料庫伺服器。Postgres 容器可能尚未啟動，也可能已啟動但尚未就緒。執行 docker compose --env-file .env -f infra/compose/docker-compose.yml ps，確認 postgres 服務回報 healthy，因為 compose 檔案設定了每三秒執行一次的 health check。容器持續重新啟動，通常表示 pgdata volume 是以不同的認證資訊建立。docker compose ... down -v 會清除該 volume，連同其中的資料一併刪除。

連接埠已被使用。 如果其他程序已占用 5433，啟動 Postgres 時會因 bind: address already in use 而失敗。最常見的原因是先前的 Rakazo stack 未停止。sudo ss -lntp | grep 5433 可顯示占用該連接埠的程序。

Bot 始終取得不到電腦。 使用 SANDBOX_PROVIDER=docker 且沒有 rakazo/computer:local image 時，沒有可啟動的內容。docker image ls rakazo/computer 可在一行中說明原因，pnpm sandbox:build 則可修正問題。如果 supervisor 無法連線至 Docker socket，也無法建立容器；錯誤訊息會指出路徑：permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock。

長指令執行到一半就終止。 .env.example 設定 SANDBOX_COMMAND_TIMEOUT_MS=300000，因此 bot 的電腦中執行的單一指令會在五分鐘後中止。對於執行時間較長的 build，請提高此值，不要直接假設 sandbox 已崩潰。

pnpm install 以難以理解的方式失效。 先檢查 node -v。工作區宣告了 >=22；如果 Node 版本較舊，錯誤會出現在相依套件程式碼中，而不是顯示版本不相容的訊息。

本機登入正常，但透過網域登入失敗。 BETTER_AUTH_URL、WEB_ORIGIN 與 API_URL 都必須與網址列中的公開 origin 相同，包括 scheme。通常是其中一項仍留有過期的 http://127.0.0.1:5173，導致 session 始終無法維持。

更新固定版本的程式碼

self-host 文件中的升級流程很簡短：拉取新的原始碼、執行資料庫 migration，然後重新啟動 API 和 worker。

./scripts/backup.sh
git fetch --all
git checkout NEW_COMMIT_SHA
pnpm install
pnpm --filter @rakazo/db migrate
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml up -d --build

先備份。Migration 只能向前執行，而 beta 版本不會提供可依賴的復原路徑。套用變更前，先閱讀固定 SHA 與新 SHA 之間的 commits，因為這麼早期的專案可能未公告就重新命名環境變數；缺少變數時，服務可能會啟動後立即結束。若你仍在評估 Rakazo 是否值得執行，自架 AI agent 的整理會介紹同類別的其他選項，以及維持各選項運作所需的成本。

FAQ

我可以在 1 GB 的 VPS 上執行 Rakazo 嗎？

不行。Postgres、API、worker、sandbox supervisor 與 web app 會同時執行；使用 SANDBOX_PROVIDER=docker 時，每個處於喚醒狀態的 bot 還會增加一個包含圖形桌面與瀏覽器的容器。專案文件指出，只有在由 E2B 提供 bot 桌面時，2 vCPU 與 4 GB 才足以執行 API、worker 與 Postgres。請將 4 GB 視為 control plane 的最低需求；若桌面在你的機器上執行，則需要更多資源。

在伺服器上使用 desktop sandbox provider 安全嗎？

不安全。desktop 會以執行該程序的使用者身分，直接在 API 與 worker 主機上執行 bot 的命令；該使用者可存取的檔案與憑證也都可能被使用。儲存庫明確表示，不應在公開或共用伺服器上使用它。每個 bot 使用一個容器時，請使用 docker；需要讓多個人登入時，請使用 e2b。

我應該安裝哪個版本的 Rakazo？

截至 16 August 2026，只有一個 tag：v0.1.0-beta。該 tag 於 13 August 2026 發布，並標示為 prerelease。請 checkout 它所指向的 commit 53b119a68d9ef843d23aa3b7e3719b6be7b51fdb，不要追蹤 main。branch 可能在你未察覺時移動，tag 也可能被重新指向，因此兩者都無法識別可返回的固定版本。請記錄該 commit，因為只有知道哪個版本可正常運作，才能回復。

OpenRouter API key 應該放在哪裡？

放在 .env 中，設定為 OPENROUTER_API_KEY；不要放在會提交至版本控制的 compose 檔案中。儲存庫中的兩個 compose 命令都會傳入 --env-file .env，因此該值會傳到容器，不會寫入受追蹤的 YAML。你也可以留空，並在 onboarding 期間於應用程式中貼上 key。請在 provider 端為該 key 設定支出上限，因為陷入迴圈的 bot 會持續呼叫模型，直到有機制停止它。

我需要網域名稱與 TLS 嗎？

若不只是進行初步測試，就需要。production compose 檔案會執行 Caddy 並自動取得憑證，而 RAKAZO_HOST、BETTER_AUTH_URL、WEB_ORIGIN 與 API_URL 都必須使用相同的公開 HTTPS origin。若只是初步查看，可以略過網域：執行 pnpm dev，並透過 SSH 轉送 port 5173，而不要將該 port 公開。