RakazoをVPSでセルフホストする方法
Rakazoを自分のVPSで動かす手順です。Node 22、pnpm、Postgres、Graphile WorkerをDocker Composeで構成し、sandboxの選択、キー管理、必要なリソースを正直に解説します。
Rakazo のセルフホストで実際に動くもの
Rakazo のセルフホストでは、1 台の Linux サーバー上で 5 つのものを動かします。PostgreSQL、Graphile Worker プロセス、API、Web アプリケーション、そして bot のコンピューターとして機能する sandbox コンテナです。Rakazo は Grok Bot に代わるオープンソースのソフトウェアで、Apache 2.0 ライセンスの下で elie222 が公開しています。各 bot には、それぞれの会話、メモリ、ルーチン、履歴があります。ワークスペース内の他の bot と 1 つの Team Computer を共有しますが、Private Computer を割り当てることもできます。また、他の bot や短時間だけ動作するサブエージェントを起動できます。この文にある「メモリ」、「サブエージェント」、「ツール呼び出し」の意味が分かりにくい場合は、まず エージェントが実際に動作する仕組みを段階的に学ぶ のに半日ほどかけるとよいでしょう。以下の設定の多くは、bot が起動したときに何をしているかをイメージできて初めて理解できるためです。
最後の点が、デスクトップではなく VPS(仮想プライベートサーバー)で運用する理由です。メモリを保持し、スケジュールされた処理を実行する bot は、利用者が寝ている間も到達可能でなければなりません。サスペンドするラップトップでは、キューの処理が止まります。
Rakazo は 2026 年 10 月時点でも beta と説明されています。現在は安定版の番号を付けたリリースも公開されていますが、完成したアプライアンスではなく、動作する構成として扱ってください。スタック全体は TypeScript で構成されています。Web アプリケーションには React 19 と Vite、API には Hono、データベースには Prisma と Postgres、アカウント管理には Better Auth、バックグラウンドジョブには Graphile Worker を使用します。Graphile Worker は Postgres 内にキューを保存するため、Redis や 2 つ目のデータストアを運用する必要はありません。.env.example は WAKEUP_DRIVER=graphile を設定します。つまり、bot の起動は Postgres に保存されたジョブとして処理されます。Postgres を停止すると、スケジュールされた bot の処理もすべて停止します。既存の製品を使うのではなく、複数の部品からエージェントを組み立てたい場合は、コンポーネントから独自のエージェントを構築する という別の方法があります。
1 GB プランでは対応できない理由
プロセス数を数えてみます。Postgres が 1 つです。API は Node プロセスです。worker が 2 つ目です。Web アプリが 3 つ目です。sandbox supervisor が 4 つ目です。さらに bot 用のコンピューターがあります。デフォルトでは、グラフィカルな Linux デスクトップを収容する共有 Team Computer コンテナが 1 つあり、アクティブな bot ごとに個別の X display と Chrome プロセスが動作します。
プロジェクトの self-host ドキュメントには、ホストのサイズが記載されなくなりました。27 October 2026 に確認した v0.3.5 のドキュメントには、ソフトウェア要件だけが記載されています。ただし、コンピューター単位の上限は示されています。Docker sandbox では、RAKAZO_COMPUTER_MEMORY のデフォルトが 2g、RAKAZO_COMPUTER_CPUS のデフォルトが 2 です。この上限は bot ごとではなく、コンピューターごとに適用されます。各 workspace にはデフォルトで 1 つの Team Computer が割り当てられ、アクティブな Team bot はすべてその中でデスクトップとブラウザーを実行するため、全 bot で 2 GB と 2 コアを共有します。Private Computer に移動した bot だけが、専用のコンテナと上限を持ちます。SANDBOX_PROVIDER=docker を設定すると、これらのデスクトップが control plane に加えて VPS 上で動作するため、4 GB は目標値ではなく最低ラインになります。複数の bot を同時に起動したままにする予定なら、8 GB から始めてください。共有コンピューターが実際にそのメモリを使用できるように RAKAZO_COMPUTER_MEMORY を増やし、bot の動作中に docker stats で実際の使用量を測定してください。メモリ使用量を左右するのは sandbox 内のブラウザーなので、スペック表だけでは判断できません。小さなマシンで同時に実行するブラウザーが多くなりすぎないようにするには、正の値の SANDBOX_TEAM_SCREEN_LIMIT を設定します。これにより、Docker Team Computer 上のアクティブなデスクトップ数を制限できます。提供時の 0 では上限がありません。全体のメモリに余裕がない場合は、RAKAZO_COMPUTER_MEMORY に 1536m のような小さい値も指定できます。agent 用のマシンのサイズを決める一般的な方法については、agent VPS に実際に必要な RAM と CPU の量で測定方法を詳しく説明しています。
この状態の悪化を防ぐ設定が 1 つあります。.env.example の提供時の値は SANDBOX_IDLE_MS=600000 で、コメントには、その時間だけアイドル状態が続くとコンピューターを一時停止または停止すると記載されています。10 分間アイドル状態になると、コンピューターは停止します。指定できる最小値は 30000 で、0 にするとアイドル時のスリープが無効になります。同じコメントでは、アイドル状態のコンピューターに費用がかからない Docker self-host では 0 が推奨されています。これにより、長時間実行するアプリケーションとセッションが起動したままになります。これは費用には当てはまりますが、メモリには当てはまりません。小さな VPS ではタイマーを有効なままにしてください。有効にしないと、起動したすべてのコンピューターと、その中のすべてのブラウザーが動作し続けます。
ディスク容量も考慮が必要です。sandbox image、Node modules、Postgres volume が 1 台のディスクを共有するため、40 GB が妥当な開始点です。
クローンする前にバージョンを固定する
Rakazo は急速に変化しており、main はリリースではありません。2026 年 11 月 9 日時点では、2026 年 11 月 4 日に公開された v0.8.0 が Latest として示されているリリースです。このガイドでは、2026 年 10 月 25 日に公開された v0.3.5 に固定しています。
git clone https://github.com/elie222/rakazo.git
cd rakazo
git checkout f31e3c0699f086d663637c4107858c238a086fb3
git log -1 --format='%H %ci'このコミットが v0.3.5 の指す先です。ブランチやタグではなく、コミットを固定してください。ブランチは次の git pull で変わる可能性があります。タグもメンテナーが付け替えられる可変のラベルなので、どちらも後から戻れるツリーを一意に識別できません。コミット識別子は変わりません。ほかのサーバー情報と一緒に記録してください。アップグレードで問題が起きたとき、安価な対処は git checkout <old commit> と再構築ですが、動作していたコミットが分からなければ実行できません。固定した README では Rakazo を beta としているため、ここまで正確に固定する手間には価値があります。意図的なリリースを長期間続けているプロジェクトなら、公開済みのタグに固定しても構いません。小規模なセルフホストスタックである openGym がその例です。
要件: Node 22、pnpm 9、Docker
node -v
pnpm -v
docker --versionpackage.json は "engines": { "node": "^22.22.2 || ^24.0.0 || >=26.0.0" } と "packageManager": "pnpm@9.15.0" を宣言します。そのため、node -v は v22.22.2 以上の 22.x、任意の v24、または v26 以上である必要があります。22.22.2 より古い v22 はこの範囲外です。README には、Node.js 23.x と 25.x はサポート対象外であることも明記されています。NodeSource または nvm から、サポート対象の Node バージョンをインストールしてください。Corepack は Node 22 と 24 に同梱されています。Node 26 以降では、まず npm install -g corepack でインストールしてください。その後、pnpm を有効化します。
corepack enable
corepack prepare pnpm@9.15.0 --activate残りの要件は、Docker Engine と compose plugin で満たせます。self-host のドキュメントでは、bot home の volume subpath に対応するため、Docker Engine 26 以降と API 1.45 以降に加えて、curl と OpenSSL を求めています。ユーザーが daemon に接続できることも必要です。docker ps の結果が permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock なら、ユーザーを docker group に追加し、新しい login shell を開いてください。ただし、先にその権限の意味を理解してください。docker のメンバーになることは、そのマシンで root と同等の権限を持つことを意味します。この group のメンバーは、host filesystem を mount する container を起動できるためです。
.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-random-hex-characters、SCREEN_PROXY_SECRET=replace-with-32-plus-character-screen-proxy-secret、SANDBOX_SUPERVISOR_TOKEN=replace-with-32-plus-character-supervisor-token が設定されていますが、POSTGRES_PASSWORD と POSTGRES_APP_PASSWORD は空のままです。これらのプレースホルダーはすべてリポジトリで公開されているため、1 つでも残したままデプロイすると、誰でも読める Secret を使って実行することになります。それぞれにランダムな値を設定してください。ENCRYPTION_KEY には 64 個のランダムな 16 進文字が必要です。これは openssl rand -hex 32 が出力する値と一致します。その他の Secret には 32 文字以上が必要なので、base64 の行をそれぞれ 1 回ずつ実行してください。2 つの Postgres パスワードには、セルフホスト向けドキュメントで URL セーフな値が求められています。最後の行でその値を生成できるので、これもそれぞれ 1 回ずつ実行してください。データベースには 2 つのログインがあります。DATABASE_MIGRATION_URL は postgres://rakazo:REPLACE_WITH_POSTGRES_PASSWORD@127.0.0.1:5433/rakazo として設定されます。これはマイグレーションを実行する所有者です。DATABASE_URL は postgres://rakazo_app:REPLACE_WITH_POSTGRES_APP_PASSWORD@127.0.0.1:5433/rakazo として設定されます。これはアプリ専用のログインで、superuser 権限を持たず、行レベルセキュリティの対象になります。それぞれのパスワードを対応する URL に設定してください。pnpm db:migrate により、設定したパスワードで rakazo_app ログインが作成されます。
openssl rand -base64 48
openssl rand -hex 32
openssl rand -hex 24次に、データベースだけを起動してマイグレーションを実行します。
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 により、package.json で docker build -t rakazo/computer:local infra/sandboxes/computer として定義されている bot computer イメージがビルドされます。これは graphical image のため、初回のビルドでは大量のデータを取得し、時間がかかります。docker image ls rakazo/computer で作成されたことを確認してください。1 行が出力されるはずです。
ベースの compose ファイルでは、Postgres のポートを一切公開しません。そのコマンドの docker-compose.postgres-host.yml オーバーレイでは、ポートを 127.0.0.1:5433 として公開します。ただし loopback のみにバインドされるため、pnpm db:migrate や pnpm dev などのホスト側ツールから接続できます。この設定は変更しないでください。.env に POSTGRES_PASSWORD がないと、Compose は Postgres の起動を拒否します。しかし、インターネットから到達できる Postgres ポートは、パスワード攻撃を招きます。本番用 compose ファイルも同じ変数を読み込み、データベースポートは公開しません。
最初の起動
pnpm devこれにより、デフォルトでは次の 4 つが起動します。port 3100 の API、Graphile Worker、port 5173 の Vite web app、そして port 7091 の sandbox supervisor です。これらのポートが使用中の場合、pnpm dev が別の空きポート範囲を選び、URL を表示します。デフォルトのポートでは、アプリは 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 service は 127.0.0.1:5173:5173 を公開し、api service は 127.0.0.1:3100:3100 します。どちらも loopback のみを使用するため、同じトンネルを利用できます。production ファイルでは、web app はホストポートを公開せず、自身の network 上のコンテナに対してだけ 5173 を公開します。Caddy だけが port 80 と 443 を公開するため、稼働を続けるものには production ファイルとその reverse proxy を使用してください。
サーバー上で安全なサンドボックスプロバイダーはどれですか?
この設定は正しく構成する必要があります。SANDBOX_PROVIDER の .env はデフォルトで docker であり、固定されたチェックアウトでは、self-host ドキュメントに記載されたプロバイダーに加えて Railway もサポートされます。
dockerがデフォルトです。Bot computer は、pnpm sandbox:buildが作成して supervisor の下で実行するイメージから、あなたのマシン上のコンテナとして起動します。デフォルトでは、1 つの workspace に属する bot が 1 台の Team Computer を共有します。Private Computer の場合のみ、bot ごとに専用のコンテナが割り当てられます。E2B のアカウントは必要ありません。e2bは E2B 上で bot computer を実行し、E2B_API_KEYを必要とします。v0.3.5では、key を指定すれば本番環境で受け入れられ、NODE_ENVによる制限もありません。self-host ドキュメントでは、bot computer を API とデータベースを実行するホストから分離できるため、公開環境または複数ユーザーの本番環境に適していると説明されています。daytona、createos、boatは追加のリモートプロバイダーです。それぞれDAYTONA_API_KEY、CREATEOS_SANDBOX_API_KEY、BOAT_API_KEYの専用 key が必要です。railwayは Railway 上で computer を実行し、API と worker でRAILWAY_API_TOKENおよび明示的に選択したRAILWAY_ENVIRONMENT_IDを必要とします。サンドボックス専用の Railway project または environment を使用してください。desktopは、ドキュメントの表現どおり、API と worker のホスト上で bot のコマンドを直接実行します。v0.3.5では、NODE_ENVがdevelopmentまたはtestでない限り、API と worker はこれを拒否します。ただし、.env.exampleはNODE_ENV=developmentを出荷するため、pnpm devを実行するサーバーでは引き続き受け入れられます。公開サービスや共有サービスでは有効にしないでください。fakeは検証専用のエミュレーターです。runtime ではありません。noneは computer host なしで製品を起動します。
これは文字どおりに受け取ってください。desktop mode では分離境界がまったくありません。そのため bot は API プロセスを実行しているユーザーとして shell コマンドを実行し、そのユーザーの home directory、SSH key、cloud credential、.env を使用します。bot が Web ページから読み取ったテキストは、サーバー上のコマンドになります。サーバーで desktop mode を使うと、bot が認証情報を保持する状態になります。自分が操作するマシンで使用するか、まったく使用しないでください。プロバイダーを切り替えても、その Web ページ経由の経路をコンテナで囲むだけで、閉じることはできません。bot 専用の SearXNG 検索バックエンドを用意することで、検索側から同じインジェクション攻撃面をカバーできます。
docker は bot とホストの間には実際の分離境界を提供しますが、bot 同士の分離は弱いものです。デフォルトでは、bot は 1 台の Team Computer を共有します。computer runtime のドキュメントによると、Team bot は OS user、workspace、browser profile、shell、X11 access を共有します。また、bot ごとの folder は作業を整理するためのものであり、セキュリティ境界ではありません。そのため、Team bot は別の Team bot の file を読み取れます。専用の分離が必要な bot は Private Computer で実行してください。docker provider は、これを独自の network 上にある別の sibling container として実行します。ただし、これらの container を作成する supervisor は /var/run/docker.sock を mount します。self-host ドキュメントにも明記されているとおり、その socket へのアクセスは Docker host の制御と同等です。そのため、supervisor は非公開にしてください。.env.example は SANDBOX_SUPERVISOR_TOKEN を専用 credential として扱います。これは BETTER_AUTH_SECRET とは別のもので、local development の外部で Docker sandbox を使用する場合に必要です。また、GitHub 上で誰でも読める placeholder が付属しています。専用のランダムな値を設定してください。この環境で利用可能な最も強い分離を得るには e2b を使用するか、他のデータを保持していないマシンを Rakazo に割り当ててください。これは使い捨て VM で coding agent を実行する理由と同じです。agent が誤った操作をしても影響を抑える最も安価な方法は、そのマシンに価値のあるものを何も置かないことです。
モデル API キーはどこに設定しますか?
Rakazo のオプション機能であるモデル利用料の課金は、Stripe の 2 つの Secret が両方設定されている場合にのみ有効になります。キーは利用者が用意します。.env.example が PI_DEFAULT_PROVIDER=openrouter を設定するため、通常は OPENROUTER_API_KEY に設定します。各プロバイダーのキーも同じ設定で利用できます。
キーは .env に保管し、コミットするファイルには記載しないでください。リポジトリの 2 つの compose コマンドはどちらも --env-file .env を渡すため、値は git が追跡する YAML に書き込まれずにコンテナへ渡されます。OPENROUTER_API_KEY を空のままにして、サインアップ後にアプリでモデルへ接続することもできます。そのため、ENCRYPTION_KEY には配布時のプレースホルダーではなく、実際のランダムな値を設定する必要があります。
ボットがキーを使う前に、プロバイダー側でキーの利用上限を設定してください。ループするボットは、その分だけ利用料を発生させます。Rakazo には MAX_TOOL_CALLS_PER_TURN もあります。正の整数を設定すると、ツール呼び出しの予算を超えたターンをソフト停止しつつ、最後のアシスタントメッセージを生成できます。未設定、空、または 0 の場合、上限はありません。これは金額ではなくツール呼び出し回数を数えるため、プロバイダー側の利用上限の代わりにはなりません。このキーには専用の名前を付け、単独で無効化できるようにしてください。自分ではなくチーム用に設定する場合は、全員のエージェントの前段に OneCLI の単一ゲートウェイを置く方法 も同じ問題に対する別の解決策です。プロバイダーのキーを利用者ごとに 1 つずつ持たず、1 か所で管理できるためです。
開発モードから常時稼働できる構成へ
リポジトリには、本番用の compose ファイルが含まれています。このファイルは、Postgres、API、worker、Web アプリケーション、そして自動取得した TLS(transport layer security)証明書を使う Caddy を起動します。ポートを公開するサービスは Caddy だけです。bot 用コンピューターには、デフォルトで E2B を使用します。オプトイン形式のオーバーレイである infra/compose/docker-compose.prod.docker.yml を使うと、同じスタック上でローカルの Docker コンピューターを実行できます。ただし、このオーバーレイが追加する supervisor は、ホスト上で root と同等の権限を持つとドキュメントに記載されています。
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/healthスクリプトを実行する前に、鍵認証専用の deploy アカウントを作成し、そのアカウントでログインできることを確認してください。harden-host.sh は SSH のパスワードログインと root ログインを無効にし、SSH にレート制限を設定します。また、既存のプライベートネットワーク向けルールを維持したまま、UFW(uncomplicated firewall)で SSH、HTTP、HTTPS の許可ルールを追加し、fail2ban、unattended security updates、AppArmor、audit ルールを有効にします。SSH_CONNECTION がないと実行を拒否するため、コマンドでは sudo を介して渡します。さらに、3 分以内に新しい SSH セッションから変更を確認しない限り、ファイアウォールの変更を元に戻します。ログイン方法が変わり、SSH が再読み込みされるため、実行前に内容を確認してください。新しい SSH ログインに成功するまで、プロバイダーのコンソールを開いたままにしてください。
本番用の .env には、開発用のものより多くの設定が必要です。自己ホスト用ドキュメントには、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>最初の up を実行する前に、サーバーを指す A レコードを設定してください。Caddy は RAKAZO_HOST に指定された名前の証明書を要求します。その名前がこのサーバーへ解決され、HTTP 検証用のポート 80 または TLS-ALPN 検証用のポート 443 のいずれかが外部からアクセスできる必要があります。両方のチャレンジがデフォルトで有効なため、ポート 80 だけを閉じても、ポート 443 経由の証明書発行は防げません。
最初から SIGNUP_ALLOWLIST を自分のアドレスに設定してください。.env.example は SIGNUPS_ENABLED=true を提供します。これらの設定は API の起動ごとに環境から読み込まれるため、公開名でアクセスできるインスタンスでサインアップが有効になっており、許可リストが未設定だと、見つけた人は誰でも登録できます。空でない許可リストは起動のたびに適用され、保存済みのリストを置き換えます。許可リストによるサインアップでは、最初に作成するアカウントを含め、メールボックスの検証が必要です。そのため、登録前にメール配信を設定してください。メールを使えない場合、ドキュメントでは SIGNUPS_ENABLED=false で起動し、記載されたサーバー側の bootstrap コマンドでアカウントを作成する手順を示しています。この方法で作成されるのは、サーバー権限を持たない通常の検証済みアカウントです。最初に許可リストを設定してください。必要になったら、後で制限を緩和できます。同じサーバーで複数のサービスを運用しており、アプリごとに許可リストを管理するより利用者の一覧を 1 つにまとめたい場合は、前段に Authentik インスタンスを配置することで、その判断をプロキシ側へ移せます。ただし、これは Rakazo 独自の Better Auth アカウントを置き換えるのではなく、その前段に配置する構成です。
本番設定の基準として、リポジトリ内の docs/self-host.md を使用してください。これはコードとともに変更されますが、このガイドは更新されないためです。Compose が処理を担うため、通常のルールが適用されます。スタックを数か月放置して運用する場合に、--env-file と名前付きボリュームがより重要になる理由は、VPS 向け Docker Compose の基本で説明しています。
バックアップ
この構成では、Postgres と data/ ディレクトリにインスタンスのデータが保存されます。復旧には ENCRYPTION_KEY と、設定済みのコンテンツマスターキーも必要です。そのため、サーバー外にもコピーを保管してください。
./scripts/backup.sh
./scripts/restore.sh backups/BACKUP_TIMESTAMPbackup.sh は Postgres をダンプし、data/ をアーカイブします。restore.sh は開発用の Compose スタックで、空のデータベースに対して使用します。実行時はアプリケーションサービスを停止してください。また、本番環境のバックアップファイルは読み取りません。依存するマシンでは、リポジトリが提供するタイマーを使い、infra/compose/backup-prod.sh を /usr/local/sbin/rakazo-backup としてインストールしてください。検証済みのダンプとアプリケーションデータのアーカイブを /var/backups/rakazo に保存します。デフォルトでは、RAKAZO_BACKUP_KEEP で設定された最大 3 個の検証済みスナップショットを保持し、RAKAZO_BACKUP_MAX_GB で設定された 50 GiB の上限内で管理します。各実行の前に不完全なスナップショットと古い履歴を削除するため、ローテーションは自動的に行われます。/etc/rakazo/backup.env に指定した公開 recipient を使い、age で各バックアップを暗号化することもできます。これにより、サーバーは自分で読み取れないバックアップを書き込みます。このキーペアは管理下のマシンで生成し、秘密鍵をサーバーに置かないでください。recipient を指定しない場合、バックアップは平文のまま保存され、警告がログに記録されます。ただし、最初の暗号化バックアップ後は、RAKAZO_BACKUP_ALLOW_PLAINTEXT=1 で平文を明示的に許可しない限り、recipient なしの実行は失敗します。データベースと同じディスクに置かれたバックアップは、バックアップとはいえません。サーバー外へコピーしてください。さらに、必要になる前に予備のサーバーで 1 回復元してください。
失敗する理由と確認できる内容
pnpm db:migrate がデータベースに接続できない。 マイグレーションで、127.0.0.1:5433 にあるデータベースサーバーへ接続できないと報告されます。Postgres コンテナが起動していないか、起動済みでもまだ準備中であるか、5433 をホストへ公開する docker-compose.postgres-host.yml overlay なしで起動されています。docker compose --env-file .env -f infra/compose/docker-compose.yml ps を実行し、postgres サービスが healthy になっていることを確認します。compose ファイルでは、3 秒ごとに実行するヘルスチェックが設定されています。コンテナが再起動を繰り返す場合は、ログを確認します。固定された Compose スタックは、Postgres 16 の既存ボリュームを Postgres 18 へ移行するまで起動を拒否します。docker compose ... down -v でボリュームを削除できますが、データも削除されます。
ポートがすでに使用されている。 5433 を別のプロセスが使用していると、Postgres の起動時に bind: address already in use が発生します。停止し忘れた以前の Rakazo スタックが、最もよくある原因です。sudo ss -lntp | grep 5433 でプロセスを特定できます。overlay は POSTGRES_HOST_PORT からホスト側ポートを読み込むため、ポートを変更できます。ただし、DATABASE_URL と DATABASE_MIGRATION_URL も同じポートに変更する必要があります。
bot にコンピューターが割り当てられない。 SANDBOX_PROVIDER=docker があり、rakazo/computer:local イメージがない場合、起動するものがありません。docker image ls rakazo/computer でその状態を 1 行で確認でき、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 のコンピューター内で実行する 1 つのコマンドは 5 分後に終了します。sandbox がクラッシュしたと判断する前に、ビルドに時間がかかる場合はこの値を増やします。
pnpm install が分かりにくい形で失敗する。 最初に node -v を確認します。workspace では ^22.22.2 || ^24.0.0 || >=26.0.0 が指定されているため、23.x、25.x、22.22.2 より前の 22.x はすべて範囲外です。固定された .npmrc では engine-strict=true が設定されているため、pnpm install はアプリケーションの依存関係コードを実行する前に、未対応の Node バージョンを engine/version エラーとして拒否します。
ローカルではサインインできるが、ドメイン経由ではできない。 BETTER_AUTH_URL、WEB_ORIGIN、API_URL はすべて、アドレスバーに表示される URL と同じ公開 origin を、スキームも含めて指定する必要があります。いずれかに古い http://127.0.0.1:5173 が残っていると、セッションが保持されないことが一般的です。
固定したチェックアウトの更新
チェックアウトから構築した本番 Compose スタックのアップグレード手順は、self-host ドキュメントでは簡潔です。新しいソースを取得し、API、worker、Web アプリを再ビルドして再起動します。API の起動コマンドはサービス開始前にマイグレーションを適用するため、API の起動時にマイグレーションが実行されます。
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 web最初にバックアップを取得します。マイグレーションは前進のみで、beta 版では確実に戻せる手段がありません。チェックアウトが 30 August 2026 より古く、v0.1.0-beta commit を含む場合は、アップグレード前にドキュメントの 20260830200000_space_scope_names_and_user_credentials migration に関する注記を確認してください。これは協調して切り替える作業です。そのため、最初に旧 API と worker を停止し、ドキュメントに記載された Space のプライバシー境界チェックを実行します。個別のアプリログインが導入される前のチェックアウトからアップグレードする場合は、再ビルド前に .env で POSTGRES_APP_PASSWORD を設定してください。本番 Compose ファイルは、この設定がないと起動しません。ソースチェックアウト用と本番用の Compose ファイルは、Postgres 18 も実行します。既存の Postgres 16 インストールを新しい構成で起動するには、事前にドキュメントの infra/compose/upgrade-postgres.sh 手順が必要です。固定した SHA と新しい SHA の間にある commit を適用する前に確認してください。この段階のプロジェクトでは、告知なしに環境変数名が変更されることがあり、変数が不足すると、サービスが起動した直後に終了する形で現れます。そもそも Rakazo が実行対象として適切か判断中であれば、セルフホスト型 AI agent のまとめで、この分野に該当する他の選択肢と、それぞれを稼働させ続けるためのコストを確認できます。
FAQ
Rakazo を 1 GB の VPS で実行できますか?
いいえ。Postgres、API、worker、sandbox supervisor、web app がすべて同時に動作します。さらに SANDBOX_PROVIDER=docker を使用すると、bot の computer が graphical desktop を保持するコンテナを追加します。稼働中の bot ごとに個別の X display と Chrome process も必要です。これらはすべて、デフォルトでは memory 2 GB と CPU 2 個の上限内で動作します。v0.3.5 の self-host doc にはホストサイズの記載がありません。control plane だけでも 4 GB を最低量と考え、desktop を自分のマシンで実行する場合はさらに増やしてください。
desktop sandbox provider はサーバー上で安全ですか?
いいえ。self-host doc では、desktop が API と worker のホスト上でコマンドを直接実行すると説明されています。そのため bot は、その process を実行しているユーザーとして動作し、そのユーザーのファイルと credentials にアクセスできます。v0.3.5 では、API と worker は development および test mode 以外でこれを拒否します。しかし pnpm dev を実行しているサーバーは development mode で動作し、受け入れてしまいます。公開サーバーや共有サーバーでは無効にしてください。workspace のほかの bot とファイルを共有させたくない場合は、bot に Private Computer を割り当てる docker を使用してください。複数のユーザーがサインインする場合は e2b を使用します。
どのバージョンの Rakazo をインストールすべきですか?
2026 年 11 月 9 日時点で、最新のリリースは 2026 年 11 月 4 日に公開され Latest と表示されている v0.8.0 です。このガイドに従う場合は、main を追跡したり、8 月の v0.1.0-beta prerelease を使用したりせず、固定した v0.3.5 のコミット f31e3c0699f086d663637c4107858c238a086fb3 を checkout してください。ブランチは変わる可能性があり、タグも付け替えられるため、どちらも後から戻れるツリーを一意に識別できません。コミットを記録してください。動作していたものが分からなければ、rollback はできません。
OpenRouter API key はどこに設定しますか?
.env に OPENROUTER_API_KEY として設定します。コミットする compose file には決して記載しないでください。repository の両方の compose command は --env-file .env を渡すため、値は追跡対象の YAML に書き込まずにコンテナへ渡されます。空のままにして、signup 後にアプリで model を接続することもできます。provider 側で key の spending limit を設定してください。bot が loop に入ると、停止されるまで model の呼び出しを続けるためです。
domain name と TLS は必要ですか?
最初のテストを終えた後は、必要です。production compose file は Caddy を実行し、証明書を自動的に取得します。RAKAZO_HOST に公開 hostname を設定し、BETTER_AUTH_URL、WEB_ORIGIN、API_URL には同じ公開 HTTPS origin を設定してください。最初に動作を確認するだけなら domain は省略できます。pnpm dev を実行し、公開する代わりに SSH で port 5173 を転送してください。