OneCLIを自己ホストする方法と必要なVPS容量

自己ホストする OneCLI の構成

OneCLI を自己ホストすると、チームの各メンバーが専用のエージェントを使用できます。各エージェントは独自のサンドボックスで実行され、API キーはエージェントが読み取れないゲートウェイで管理されます。インストール構成は、PostgreSQL を背後に配置した Docker Compose スタックです。http://localhost:10254 から接続できます。実運用に適したサーバーを用意してください。ドキュメントに記載されたデフォルトでは、各エージェントのサンドボックスに 2 GiB のメモリが必要です。そのため、1 GB の VPS では適した負荷ではありません。

このスタックには 7 つのコンポーネントが含まれます。それぞれの役割を把握すると、このガイドの残りを読みやすくなります。

• Web dashboard（Next.js）、ポート 10254。エージェントの作成、チャット、メモリとスキルの編集、接続、Secret を管理します。
• API server、ポート 10256。制御プレーンです。データベース、会話処理、作業キューを担当します。
• Rust gateway、ポート 10255。エージェントからの外向きリクエストをインターセプトし、認証情報を注入します。
• Runner。README では、「エージェントのサンドボックスを開始、待機、破棄するコンポーネント」と説明されています。外向き通信専用で、データベースには一切アクセスしません。
• Sandbox Supervisor。README では、「各サンドボックス内で実行され、ベンダーに依存しないハーネスインターフェイスを介して通信するため、エージェントランタイムを交換可能にする」と説明されています。
• Channel adapter。Slack アプリに接続するデーモンです。エージェントは自身の名前でチャンネルや DM に応答できます。
• PostgreSQL。提供されている compose ファイルは、postgres:18-alpine を pgdata ボリュームで実行します。

名前に CLI とあっても、実体はサーバーです

OneCLI はサーバープラットフォームです。名前からは、ノート PC にインストールするコマンドラインツールを想像します。しかし、このガイドで扱うものはそれとは異なります。別個のコマンドラインクライアントは onecli/onecli-cli リポジトリにあり、ローカルのコーディングエージェントのネットワークトラフィックをゲートウェイ経由で転送します。ここでデプロイするのは、複数ユーザーに対応する Web アプリケーションです。最初のアカウントがインスタンスを所有するアカウントシステム、会話と Secret を保存するデータベース、コンテナを起動する runner で構成されます。

ユーザーごとにエージェントを割り当てる設計が、全体の基本です。README には次のように記載されています。「ユーザーごとにエージェントを作成し、必要なアクセス権を与えます。各エージェントは、認証情報を注入してポリシーを適用するゲートウェイ経由で、sandbox 内で動作します。」各エージェントには独自のファイルシステムと shell、専用の会話ページ、プラットフォームが保持する memory、そして一度作成すれば再利用できる skills があります。認証情報の扱いは、一般的な構成とは逆です。各ユーザーの環境に API key をコピーするのではなく、key を 1 回だけ保存し、使用を許可したエージェントに付与します。

開始前にサーバーで必要なもの

• Docker。Compose plugin のバージョンは 2.19 以降にしてください。compose file は、API が完了を待つ one-shot migrations service を使用しており、この依存関係の形式には 2.19 が必要です。
• メモリ。実際の制約はメモリです。プランを選ぶ前に、以下のサイジングのセクションを確認してください。
• 空いている loopback ポート 10254、10255、10256、5432。

PostgreSQL を自分でインストールする必要はありません。compose file がサービスとして起動します。Node.js や Rust も必要ありません。これらはソースからビルドする場合にのみ使用し、その手順では mise が toolchain のバージョンを固定します。

VPS 上でいくつのエージェントサンドボックスを実行できるか

Runner の公式ドキュメントには、感覚的な説明ではなく具体的な数値が示されています。各サンドボックスには 2048 MB のメモリ（RUNNER_SANDBOX_MEMORY_MB）、1 CPU（RUNNER_SANDBOX_CPUS）、512 個のプロセス（RUNNER_SANDBOX_PIDS）が割り当てられます。同時実行数の上限は 4（RUNNER_MAX_SANDBOXES）です。ドキュメントでは、この上限に対応するため、基本スタックとは別に約 10 GiB の空きメモリを確保することを推奨しています。

[
  {
    "plan": "2 GB box",
    "ram_gb": 2,
    "sandbox_slots": 0
  },
  {
    "plan": "4 GB box",
    "ram_gb": 4,
    "sandbox_slots": 1
  },
  {
    "plan": "8 GB box",
    "ram_gb": 8,
    "sandbox_slots": 3
  },
  {
    "plan": "16 GB box",
    "ram_gb": 16,
    "sandbox_slots": 7
  },
  {
    "plan": "32 GB box",
    "ram_gb": 32,
    "sandbox_slots": 15
  }
]

このスロット数はベンチマークではなく、算術計算によるものです。総メモリから PostgreSQL と 4 つの長時間稼働サービス用に約 2 GB を差し引き、2 GiB のサンドボックス上限で割っています。この計算では、2 GB box で 0 個のサンドボックスを実行できます。そのため、最安プランではホスト型エージェントをまったく実行できません。16 GB box では 7 個分の余裕があり、デフォルト上限の 4 を十分に上回ります。また、Runner のドキュメントが求める約 10 GiB の空きメモリも確保できます。32 GB box では 15 個まで増やせます。

この計算を変える要因が 2 つあります。バックグラウンドプロセスが実行中のサンドボックスは停止状態にならないため、スロットを常に占有します。したがって、最も負荷が高い 1 分間ではなく、継続的な負荷に対して RUNNER_MAX_SANDBOXES を見積もる必要があります。もう 1 つは、CPU より先にメモリが不足することです。各サンドボックスの CPU 上限は 1 つです。そのため、負荷の高いエージェントが 4 つあれば 4 コアを必要としますが、アイドル状態でも起動中のエージェントが 4 つあれば 8 GiB を占有します。

Docker Compose で OneCLI をインストールする

上流のセルフホスティング手順には、次の一連のコマンドがそのまま記載されています。compose ファイルの隣にある docker/.env に3つの Secret を書き込み、その後でスタックを起動します。

git clone https://github.com/onecli/onecli.git && cd onecli/docker
cat > .env <<EOF
SECRET_ENCRYPTION_KEY=$(head -c 32 /dev/urandom | base64)
GATEWAY_INTERNAL_SECRET=$(head -c 32 /dev/urandom | base64)
BETTER_AUTH_SECRET=$(head -c 32 /dev/urandom | base64)
COMPOSE_PROFILES=runner
EOF
chmod 600 .env
docker compose up -d --wait

実行する前に、このブロックを確認してください。heredoc のマーカーが引用符で囲まれていないため、シェルは各 head -c 32 /dev/urandom | base64 を実行し、リテラル文字列ではなく実行結果を書き込みます。SECRET_ENCRYPTION_KEY は、データベース内のすべての Secret に使用する AES-256-GCM 鍵です。GATEWAY_INTERNAL_SECRET は、gateway が API に接続する際の認証に使用します。BETTER_AUTH_SECRET は、セッション Cookie に署名します。最も重要なのは COMPOSE_PROFILES=runner です。runner service は Compose profile の背後にあるため、これを省略するとスタックは正常に起動したように見えても、agent sandbox は起動しません。

--wait は、すべての service が healthy を報告するまでシェルを待機させます。そのため、ゼロ以外の終了コードが問題を示す最初の合図になります。次に、実際に起動したものを確認します。

docker compose ps
docker compose logs migrations

バージョンを固定してください。ONECLI_VERSION で全 service の tag を一括指定できます。RUNNER_AGENT_IMAGE が別の場所を指定しない限り、agent sandbox image もその tag に従います。2026年8月19日時点の current release は v2.0.1 で、2026年8月18日に公開されています。同じファイルに追加して、スタックを再度起動します。

echo 'ONECLI_VERSION=v2.0.1' >> .env
docker compose up -d --wait

curl -fsSL https://onecli.sh/install | sh という installer もあり、~/.onecli/.env に設定を書き込み、同じ処理を実行します。Compose を使う方法では、実行前にすべてのファイルを確認できます。また、すでに他の Compose stack が稼働しているホストでは、この方法を使用します。ソースからの build という第3の方法もあります。clone した repository で pnpm install、続いて pnpm run setup として説明されています。この方法には mise、gateway 用の Rust、さらに Docker が必要です。コードを変更する予定がある場合に使用します。

ラップトップからダッシュボードにアクセスする

提供されている compose ファイルの公開ポートはすべて ${ONECLI_BIND_HOST:-127.0.0.1} にバインドされます。VPS では、ダッシュボードは稼働していても、ホスト外部からアクセスできません。このデフォルト設定は正しいため、そのまま使用してトンネルを作成します。

ssh -N -L 10254:127.0.0.1:10254 you@your-server

次に、ラップトップで http://localhost:10254 を開きます。通信は SSH 接続を経由するため、暗号化されていないダッシュボードをパブリックインターネットに公開せずに済みます。ファイアウォールで追加のポートを開く必要もありません。

ONECLI_BIND_HOST=0.0.0.0 を設定すると、ダッシュボードが通常の HTTP で公開され、PostgreSQL も同時に公開されます。複数人がダッシュボードを利用する場合は、10254 番ポートの前段に TLS 対応のリバースプロキシを置き、バインド先のホストは変更しないでください。インスタンスの所有者を設定する前に実施します。上流のドキュメントでは、その理由を次のように明確に説明しています。「これを実施するまで、インスタンスには所有者がいません。アクセス可能なホストでは、最初に到達した人が所有者になります。」そのプロキシが他のセルフホストアプリケーションの前段にもある場合は、セルフホストのシングルサインオン基盤 を介して認証を転送できます。これにより、チームがすでに使用しているログインの背後にダッシュボードを配置できます。1 か所で利用者を削除すれば、このアクセス経路も閉じられます。

最初のアカウントを作成し、モデルキーを付与する

ダッシュボードを開き、すぐにアカウントを作成します。このアカウントがインスタンスを所有します。アカウントを作成すると、参加には招待が必要になります。

エージェントを作成する前に、モデルキーを保存します。ホスト型エージェントには、付与済みのモデルキーが必要です。手順の順序も重要です。ダッシュボードにキーを保存し、エージェントに付与してから、会話を開始します。付与を省略すると sandbox は起動せず、エージェントが何もせず停止した状態になります。

付与する権限は必要最小限にします。各エージェントは付与されたものだけを使用でき、gateway はすべてのリクエストでこの制限を適用します。そのため、1 つの repository を読み取るエージェントが、決済プロバイダーのキーへアクセスする経路を持つことはありません。同じ付与リストで支出も制御できます。個人用エージェントが所有するすべてのモデルを呼び出せる場合、利用者ごとに請求が発生します。そのため、10 個を配布する前に、エージェントがモデル呼び出しに使える金額を制限する方法を確認してください。

エージェントからキーを隔離するゲートウェイの仕組み

このゲートウェイは Rust で実装された HTTPS プロキシで、10255 番ポートで待ち受けます。エージェントの HTTP クライアントをゲートウェイに向け、エージェントには実際の認証情報ではなくプレースホルダーの認証情報を持たせます。ゲートウェイは送信リクエストをエージェントに付与された権限と照合し、実際の Secret を復号してリクエストに差し替え、転送します。Secret は AES-256-GCM（advanced encryption standard、256-bit、Galois/counter mode）で暗号化して PostgreSQL に保存し、復号するのはリクエスト処理時だけです。すべての呼び出しをエージェントの識別情報と宛先付きでログに記録するため、キーを 10 人分の shell profile に保存する場合には得られない監査証跡を確保できます。

デプロイ方法を決める仕組みは 2 つあります。

• HTTPS のインターセプトは中間者攻撃の構成です。ゲートウェイがローカルの認証局を生成し、エージェントがそれを信頼します。ゲートウェイはエージェントとの TLS 接続を終端し、upstream service へ新しい接続を開きます。そのため、HTTP クライアントがゲートウェイの認証局を信頼しないエージェントでは、認証エラーではなく証明書検証エラーが発生します。
• エージェントは Proxy-Authorization ヘッダーで自身を識別します。1 台のホスト上でエージェントとゲートウェイが内部 Docker network を共有する場合、このヘッダーが自分で管理していないネットワークを通過することはありません。別のホストにあるエージェントをゲートウェイへ接続する場合、プロキシポート自体に TLS が必要です。このヘッダーは bearer token だからです。

注意すべきトレードオフは、ゲートウェイが設計上、エージェントから送信されるすべてのリクエストを平文で読み取ることです。ゲートウェイはホスト上で最も機密性の高いプロセスです。ホストを適切に保護し、最小権限の Linux ユーザーを使用してログインできる人を少数に限定してください。

Runner に受信ポートが不要な理由

Runner は送信専用です。ドキュメントにも、「外部から到達できるポートを保持しないため、laptop、homelab、NAT 配下の VPC のいずれでも、受信設定、トンネル、TLS 終端を必要とせずに動作する」とあります。NAT は network address translation、つまり家庭用ルーターが行う処理です。Runner は control plane に接続して処理を取得するため、転送するポートも開放するポートもありません。

この設計は sandbox network で効果を発揮します。compose file では、internal: true としてマークされた 2 つ目の network を定義しています。Docker では、これは host の外部へ向かうルートがまったくないことを意味します。Sandboxes はこの network に参加します。Gateway は両方の network に接続されているため、外部へ出る唯一の経路です。Runner のドキュメントには、この点が明確に記されています。「gateway が両方の network に接続された internal network によって、gateway 経由だけの egress が単なる推奨ではなく境界として機能する」。Agent が任意に選んだアドレスへソースコードを送信しようとしても、そのためのルートはありません。

上の説明をそのまま信頼せず、自分の環境で確認してください。

docker network ls
docker network inspect onecli-sandboxes | grep -i internal

"Internal": true と表示されるはずです。false と表示される場合、egress control が無効であり、gateway は再び単なる推奨にすぎません。docker network ls に表示された sandbox network name を使用してください。onecli-sandboxes は default にすぎません。

OneCLI の sandbox はどの程度強固か

このセクションはゆっくり読んでください。プロジェクト自身の説明では「sandboxed」という言葉が大きな意味を持つ一方、その仕組みは1か所でしか文書化されていないためです。

README には、各 agent が「独自の分離された sandbox と、ファイルシステムおよび shell」を取得すると記載されています。また、Sandbox Supervisor は「各 sandbox 内で動作し、vendor-neutral な harness interface を介して通信するため、agent runtime を交換できる」コンポーネントだと説明されています。しかし、どちらの文も、その分離が何で構成されているかは説明していません。runner のドキュメントには説明があります。デフォルトの backend は Docker (RUNNER_BACKEND=docker) であり、sandbox は memory cap、CPU cap、process cap を設定して internal network に接続した Docker container です。コードには他の backend に対応するための拡張ポイントがあり、ドキュメントでは Kubernetes や microVM などを、誰かが実装すべき module として挙げています。現在、あなたの環境での sandbox は container です。

ドキュメントに記載されていない点も、同じ程度に重要です。threat model はありません。Docker daemon を rootless で実行すること、user namespace remapping、Docker のデフォルト以外の seccomp や AppArmor profile について説明がありません。gVisor や microVM のような kernel boundary も保証していません。したがって、狭く解釈してください。cap は resource cap です。internal network は実際の egress control です。agent と host の分離は、stock Docker container が提供する範囲に限られ、container は host kernel を共有します。

もう1つ、考慮すべき事実があります。runner service は /var/run/docker.sock を mount します。sandbox を作成するためです。Docker socket へのアクセスは host の root 権限と同等です。その API を呼び出せるユーザーは、host filesystem を内部に mount した container を起動できるためです。Docker を使用する runner はすべて、この仕組みで動作します。その結果、runner process は gateway と同じ程度に慎重に扱う必要があります。

upstream が境界を文書化するまでは、その境界が実証されていないものとして扱ってください。実際には、次の3つを習慣にします。

1. OneCLI は、それ以外の処理を行わない box で実行します。無関係な production service、共有 database、他 team の data を同じ環境に置かないでください。
2. sandbox 内で任意の code execution が可能になった agent は host に到達できると想定し、その結果が発生しても復旧できるよう、backup を box の外部に保管します。
3. agent が隔離されていると同僚に伝える前に、apps/runner/src を読むか、upstream に確認してください。

文書化された境界がどのように記述されるか、その場合に upstream へ確認すべき質問については、実際の agent sandbox の境界がどのようなものかと比較してください。違いは、仕組みと、その仕組みで防げないことが誰かによって文書化されているかどうかです。

ライセンスの区分と、構築前に確認する理由

OneCLI のコア部分は Apache-2.0 であり、本番環境でのセルフホスティングも許可されています。ee/ という名前のディレクトリは、別の OneCLI Enterprise License の対象です。開発、テスト、評価では無料ですが、本番利用にはサブスクリプションが必要です。2026年8月18日の v2.0.1 のリリースノートには、GitHub が検出できる Apache-2.0 ライセンスファイルを復元したと記載されています。そのため、リポジトリページのバッジは最近変更されています。別の日付に作成された概要ではなく、実際にデプロイするタグを確認してください。

cd onecli && find . -type d -name ee -not -path '*/node_modules/*'

これらのパス以下にあるものは、商用版に該当します。利用する予定の機能がそこにある場合は、その機能を前提に運用手順を構築する前に価格を確認してください。

アップグレード、移行、そして失ってはならない 1 つのファイル

アップグレードでは、バージョンを更新して再起動します。ワンショットの migrations サービスは、すべての up の前に API より先に実行されます。migration に失敗した場合、スタックは起動を拒否します。中途半端なスキーマに対してサービスを提供することはありません。この動作が必要です。アップグレードの失敗が、気付かないデータ破損ではなく停止として現れるためです。docker compose logs migrations に理由が示されています。

cd onecli/docker
docker compose pull
docker compose up -d --wait
docker compose logs migrations

代わりに install script でインストールした場合は、手動で取得せず、その script を再実行してください。これにより、compose file と参照する image のバージョンが一致した状態に保たれます。

2 つの項目をバックアップしてください。PostgreSQL には agents、conversations、memory、暗号化された secrets が保存されます。docker/.env ファイルには SECRET_ENCRYPTION_KEY が保存されます。この key がないと暗号化された secrets を読み取れないため、データベースの dump だけでは使用可能な状態に復元できません。

cd onecli/docker
docker compose exec -T postgres pg_dump -U onecli onecli | gzip > ~/onecli-db.sql.gz
install -m 600 .env ~/onecli-env.backup

両方のコピーをサーバー外に保管してください。手順は、状態を保持する Compose stack で必要なものと同じです。すでに定期的に Docker Compose stack をバックアップしてアップグレードしている場合は、この 2 つの path を対象に追加して、あとは自動運用に任せてください。

動作しない場合

• スタックが healthy にならず、docker compose up -d --wait が 0 以外の終了コードで終了する場合は、まず docker compose logs migrations を確認します。API は意図的にこのサービスの起動を待機するためです。
• エージェントが待機したままでサンドボックスが作成されない場合は、COMPOSE_PROFILES=runner が docker/.env に含まれていることと、docker compose ps に runner が登録されていることを確認します。次に、エージェントに model key が付与されていることを確認します。model key がないとサンドボックスは起動しません。
• スロットが残っていない場合は、RUNNER_MAX_SANDBOXES の既定値が 4 であることを確認します。バックグラウンドプロセスが実行中のサンドボックスは、スロットを継続的に占有します。docker ps で実際に稼働しているプロセスを確認できます。
• コンテナが消える、またはホストの動作が遅くなる場合は、メモリ不足です。dmesg -T | grep -i oom にカーネルがメモリ不足でプロセスを強制終了した記録があります。1 つのサンドボックスだけで 2048 MB を使用することもあります。
• エージェントの HTTPS 呼び出しが認証エラーではなく、証明書検証エラーで失敗する場合は、HTTP クライアントが gateway の認証局を信頼していません。
• エージェントを削除した後も古いコンテナやボリュームが残る場合があります。runner は 60 秒ごとに状態を調整し、RUNNER_ORPHAN_GRACE_SECONDS より古い孤立リソースを削除します。RUNNER_ORPHAN_GRACE_SECONDS の既定値は 3600 です。リークと判断する前に 1 時間待ってください。

あなたが実行するものとして、これは適切ですか？

適合性の確認は簡単です。複数の人がそれぞれ agent を必要とし、認証情報を一元管理したい場合、OneCLI には導入する価値があります。ローテーション対象のストア、確認すべき監査ログ、ある人のアクセスを取り消すと実際にそのアクセスも無効になるダッシュボードを、1 か所に集約できます。これは実際の運用上の課題です。API key を 6 台の laptop にコピーするよりも、適切な解決策です。

1 人で使う場合、得られるものに対して仕組みが大きすぎます。1 つの agent のために PostgreSQL、control plane、gateway、runner を運用することになりますが、gateway が解決する認証情報の課題は、key を持つ人が自分だけならほとんど発生しません。代わりに、小規模な box で単一の harness を実行してください。VPS 上の単一 agent harness なら、必要なメモリを大幅に抑えてこの役割を果たせます。まだ方向性をまったく決めていない場合は、セルフホスト型 AI agent の比較を最初に確認するほうが低コストです。

FAQ

OneCLI をセルフホストするための最小サーバー要件は何ですか？

Compose plugin 2.19 以降を備えた Docker と、十分なメモリが必要です。PostgreSQL は compose file に含まれているため、個別にインストールする必要はありません。必要なメモリはプランを左右します。runner はデフォルトで agent sandbox ごとに 2048 MB を割り当てます。ドキュメントでは、デフォルト上限の 4 個の sandbox を動かすため、base stack とは別に約 10 GiB の空きメモリを求めています。さらに、PostgreSQL と 4 個の長時間稼働サービスに約 2 GB が必要です。4 GB のサーバーでは、agent を一度に 1 個実行できます。16 GB のサーバーなら、デフォルト上限を余裕を持って処理できます。1 GB または 2 GB の VPS では、hosted agent をまったく起動できません。

OneCLI には PostgreSQL が必要ですか、それとも SQLite を使用できますか？

PostgreSQL が必要です。DATABASE_URL は PostgreSQL connection string として文書化されています。提供される compose file は postgres:18-alpine を pgdata volume とともに実行し、別の migrations service が API の起動前に schema を適用します。SQLite の選択肢は文書化されていません。すでに別の場所で PostgreSQL を実行している場合は、DATABASE_URL をその PostgreSQL に向けて、migrations service は維持してください。migration に失敗すると、適用途中の schema でサービスを続けるのではなく、stack 全体が停止するためです。

OneCLI の agent sandbox は実際のセキュリティ境界ですか？

文書化されている仕組みは、メモリ、CPU、プロセス数に上限を設定した Docker container です。この container は internal: true とマークされた network に接続されるため、gateway 以外への経路を持ちません。egress 制御は実際に機能し、docker network inspect で確認できます。一方、host からの分離は container 相当です。upstream は threat model、rootless または user namespace に関する保証、gVisor や microVM などの kernel 境界を公開していません。runner は /var/run/docker.sock も mount します。これは host 上の root と同等です。upstream が明示するまでは、agent と host の境界が安全であるとは判断しないでください。OneCLI は専用サーバーで実行し、バックアップはそのサーバーの外部に保管してください。

OneCLI のために inbound port を開く必要はありますか？

必要ありません。runner は outbound-only で、外部から到達できる port を保持しないため、tunnel なしで NAT の背後でも動作します。compose file はデフォルトで dashboard、gateway、API、PostgreSQL を 127.0.0.1 に bind します。dashboard には SSH tunnel 経由でアクセスしてください。複数人が利用する場合は、port 10254 の前段に TLS 対応の reverse proxy を配置します。10255 の gateway は agent 用です。1 台のサーバー構成では、agent は内部 Docker network 経由で gateway に接続します。

社内で OneCLI を無料で使用できますか？

core は Apache-2.0 で、商用ライセンスなしで self-hosted の本番利用が認められています。ee/ という名前の directory には OneCLI Enterprise License が適用されます。このライセンスは開発、テスト、評価では無料ですが、本番利用には subscription が必要です。対象となる範囲は release ごとに変わります。2026 年 8 月 18 日の v2.0.1 notes には、GitHub で検出可能な Apache-2.0 license file を復元したことが記載されています。そのため、特定の機能を前提に workflow を構築する前に、実際に deploy する tag の LICENSE と ee/ directory を確認してください。