SSD Nodes Learn Hosting plans →
ガイド Matt Connor著者 Matt Connor

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

OneCLIを自己ホストし、1人1エージェントのサンドボックスを構築します。Docker ComposeとPostgreSQLの構成、APIキーを守るゲートウェイ、エージェントごとに必要な2 GiBのメモリを解説します。

OneCLI を自己ホストすると得られるもの

OneCLI を自己ホストすると、チームの各メンバーに専用のエージェントが割り当てられます。各エージェントは独自のサンドボックスで動作し、API key はエージェントが読み取れない gateway に保持されます。インストールは Docker Compose の stack で、背後で PostgreSQL が動作し、http://localhost:10254 からアクセスできます。実運用に耐えるサーバーを用意してください。ドキュメントに記載されたデフォルトでは、各エージェントのサンドボックスに 2 GiB のメモリ上限が設定されます。そのため、基本 stack に必要なメモリと、エージェントが実際に使用するメモリを分けて見積もってください。

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

  • Web dashboard(Next.js、ポート 10254)。エージェントの作成、チャット、memory と skills の編集、接続、secret を管理します。
  • API server(ポート 10256)。control plane です。データベース、会話処理、work queue を担当します。
  • Rust gateway(ポート 10255)。エージェントからの送信リクエストをインターセプトし、認証情報を注入します。
  • Runner。README では、「エージェントのサンドボックスを起動、待機、破棄するコンポーネント」と説明されています。送信専用で、データベースには一切アクセスしません。
  • Sandbox Supervisor。README では、「各サンドボックス内で動作し、vendor に依存しない harness interface を介して通信するため、エージェント runtime を交換可能にするコンポーネント」と説明されています。
  • SSH terminator(ポート 10257)。README では「SSH の入口」と説明されています。API が発行する短期間有効な証明書で SSH を終端し、各セッションをエージェントのサンドボックスへ中継します。Runner と同じ runner profile で動作します。
  • Channel adapter。Slack app に接続する daemon です。エージェントは自分の名前で channel と DM に応答できます。
  • PostgreSQL。提供されている compose file では、postgres:18-alpine を pgdata volume とともに実行します。

名称は CLI ですが、製品はサーバーです

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

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

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

  • Docker。Compose plugin は version 2.24.0 以降にしてください。付属の compose file は required: false を使用した任意の env_file mapping を使います。Docker がこれをサポートするのは 2.24.0 以降です。移行時のコメントでは、2.19 以上が up --wait 配下の one-shot dependency をサポートするための下限と説明されています。ただし、compose file の任意の environment file までは対象になりません。
  • Memory。実際の制約になるため、plan を選ぶ前に下記の sizing section を確認してください。
  • 空いている loopback port 10254、10255、10256、10257、5432。Port 10257 は SSH の入口で、この guide が有効にする runner profile で開始します。

PostgreSQL を自分で install する必要はありません。compose file が service として起動します。下記の setup wizard では、host に Node.js と pnpm が必要です。コード自体を扱う場合も mise を使用して toolchain を固定します。gateway 用の Rust も対象です。

VPS にいくつのエージェントサンドボックスを収容できるか

runner のドキュメントには、推測ではなく具体的な数値が記載されています。各サンドボックスには、メモリ 2048 MB (RUNNER_SANDBOX_MEMORY_MB)、CPU 1 個 (RUNNER_SANDBOX_CPUS)、プロセス 512 個 (RUNNER_SANDBOX_PIDS) の上限があります。同時実行数の上限は 4 (RUNNER_MAX_SANDBOXES) です。ドキュメントでは、この上限に対応するため、ベーススタックとは別に約 10 GiB の空きメモリを確保することを推奨しています。

グラフAgent memory budgets per box, using the documented 2 GiB cap
このグラフのデータ
[
  {
    "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 などの常駐サービス用に約 2 GB を見込んだ容量を引き、2 GiB のサンドボックス上限で割っています。この前提では、2 GB box はメモリ上限まで使用する 0 個のサンドボックス分を確保できます。0 は、これらの前提ではメモリ上限まで使用する予算がないことを示すだけであり、Docker がエージェントの起動を拒否するという意味ではありません。16 GB box では 7 個分の余裕があり、デフォルト上限の 4 を十分に上回ります。また、runner のドキュメントが求める約 10 GiB の空きメモリも上回ります。32 GB box では 15 個まで増やせます。4 個を超えて同時実行するには、RUNNER_MAX_SANDBOXES も引き上げる必要があります。

この計算には、2 つの補正要因があります。バックグラウンドプロセスが動作しているサンドボックスは停止状態にならないため、スロットを恒久的に保持します。そのため、RUNNER_MAX_SANDBOXES は最も負荷が高い 1 分間ではなく、継続的な負荷を基準に決めます。プラットフォームにも上限があります。デフォルトでは、各 runner が保持できる、起動状態を維持するサンドボックスは RUNNER_MAX_SANDBOXES - 1 個までです。ただし、1 個未満にはなりません。API では MAX_HELD_AWAKE_SANDBOXES で上書きできます。この上限を超えると、最後にアイドル状態になったサンドボックスを破棄し、そのサンドボックスが監視していたプロセスを失われたものとして報告します。メモリと CPU の使用量は処理内容によって異なります。各サンドボックスの CPU 上限は 1 個なので、負荷の高いエージェント 4 個で 4 コアを使用できます。ただし、2 GiB のメモリ設定は予約量ではなく上限です。アイドル状態で起動を維持しているエージェントが 4 個あっても、自動的に 8 GiB を消費するわけではありません。

変更を検討できる Runner 設定
  • RUNNER_MAX_SANDBOXES (デフォルト 4): 同時に実行するサンドボックス数。
  • RUNNER_SANDBOX_MEMORY_MB (デフォルト 2048): サンドボックスごとのメモリ上限。
  • RUNNER_SANDBOX_CPUS (デフォルト 1): サンドボックスごとの CPU 上限。
  • RUNNER_SANDBOX_PIDS (デフォルト 512): サンドボックスごとのプロセス上限。
  • RUNNER_NETWORK_INTERNAL (デフォルト true): サンドボックスネットワークから外部への経路をなくします。有効のままにします。
  • RUNNER_SANDBOX_NETWORK (デフォルト onecli-sandboxes): サンドボックスが参加するネットワーク。
  • RUNNER_RECONCILE_SECONDS (デフォルト 60): runner が状態を調整する間隔。
  • RUNNER_ORPHAN_GRACE_SECONDS (デフォルト 3600): 孤立したコンテナとボリュームを削除するまでの経過時間。
  • RUNNER_AGENT_IMAGE: サンドボックスイメージを上書きします。指定しない場合は ONECLI_VERSION に従います。

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

上流のセルフホスティング手順にあるそのままの手順では、compose ファイルの隣に docker/.env の 3 つの Secret を書き込みます。この手順には、有効化するサービスに必要な runner token、Docker socket group、SSH credentials が含まれていません。そのため、スタックを起動する前にセットアップウィザードを実行してください。

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
cd ..
pnpm install
pnpm run setup
cd docker
docker compose up -d --wait

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

--wait は、サービスが running または healthy になり、migrations dependency が正常に完了するまで待機します。そのため、ゼロ以外の終了ステータスは、問題があることを示す最初のシグナルです。続いて、実際に起動したものを確認します。

docker compose ps
docker compose logs migrations

バージョンを固定してください。ONECLI_VERSION ですべてのサービスの tag を一度に設定できます。RUNNER_AGENT_IMAGE が別の場所を指定していない限り、agent sandbox image もその tag に従います。公開されている image tag には v prefix がないため、バージョン番号だけを指定してください。2026 年 11 月 1 日時点の current release は v2.17.0 で、2026 年 10 月 31 日に公開されています。同じファイルに追加し、文書化された upgrade path を使って、実行中の sandbox もその image に移行してください。

echo 'ONECLI_VERSION=2.17.0' >> .env
cd ..
pnpm run setup --upgrade
cd docker

curl -fsSL https://onecli.sh/install | sh という installer もあり、設定を ~/.onecli/.env に書き込んで同じ処理を行います。この installer は実行時に ONECLI_VERSION=latest を設定するため、.env ファイルだけで保持している pin は上書きされます。Compose path では、何も実行される前にすべてのファイルを確認できます。また、すでに他の Compose stack が稼働しているホストでは、この方法を使ってください。上記の checkout setup は pnpm run setup --upgrade で upgrade します。この方法ではホストに Node.js と pnpm が必要です。コード自体を変更する場合は、gateway 用の mise と Rust も必要になるため、OneCLI を変更する予定がある場合に適しています。Kubernetes では、release v2.11.0(2026 年 10 月 8 日)で Helm chart が追加されました。current chart は、Docker daemon を使わず、persistent volume を使用する Jobs として agent sandbox を実行し、必要な Secret、database、routing configuration を文書化しています。

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

同梱の compose ファイルで公開されるすべてのポートは ${ONECLI_BIND_HOST:-127.0.0.1} に bind されます。VPS では、ダッシュボードは動作していても、サーバー外部からアクセスできません。このデフォルト設定は適切です。変更せず、トンネルを使用します。

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

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

ONECLI_BIND_HOST=0.0.0.0 を設定すると、ダッシュボードが平文 HTTP で公開され、PostgreSQL も同時に公開されます。POSTGRES_PASSWORD を設定しない場合、compose ファイルのデフォルトパスワード onecli が使用されます。また、Docker socket をマウントするサービスの SSH フロントドアが、ポート 10257 で公開されます。複数のユーザーがダッシュボードを使用する必要がある場合は、TLS(transport layer security)対応のリバースプロキシを前段に置き、bind host は変更しないでください。ONECLI_EXTERNAL_URL には HTTPS URL を設定し、upstream のリバースプロキシ設定を使用します。この設定により、ダッシュボード、API、gateway のパスがそれぞれのサービスへ転送されます。プロキシを置くだけでは、外部ユーザーのアクセスを防げません。self-hosting のドキュメントによると、登録は設計上オープンになっており、無効にするスイッチはありません。ダッシュボードに到達できるユーザーは誰でもアカウントを作成できます。作成したアカウントには専用の organization が割り当てられ、招待が必要なのは自分の organization への参加だけです。ドキュメントでは、ダッシュボードをネットワーク境界の内側に置くよう推奨しています。プロキシが他の self-hosted アプリの前段にもある場合、self-hosted のシングルサインオン層 を介して forward auth を使用すれば、チームがすでに利用しているログインの背後にダッシュボードを置けます。そのため、1 か所でユーザーを削除すれば、この入口も閉じられます。

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

ダッシュボードを開き、最初にアカウントを作成します。新しいアカウントごとに専用の organization が作成され、チームメンバーは招待によって参加します。その後も登録は可能なままなので、ダッシュボードをトンネルまたは認証済みプロキシの背後に置く理由がさらに増えます。ログイン機能が導入される前のリリースからアップグレードする場合は、すぐに登録してください。self-hosting のドキュメントによると、既存のデータは最初に登録したアカウントに引き継がれます。そのため、到達可能なホストでは、そのアカウントを自分のものにする必要があります。

次に、agent を作成する前にモデルキーを保存します。ホスト型の agent には付与済みのモデルキーが必要です。手順の順序も重要です。ダッシュボードにキーを保存し、agent に付与してから、会話を開始します。付与を省略すると sandbox は起動せず、agent はモデルキーが必要だとスレッド内で説明します。

付与する権限は必要最小限にします。各 agent が利用できるのは付与したものだけであり、gateway はすべてのリクエストでこの制限を適用します。そのため、1 つの repository を読む agent から payment provider のキーに到達することはできません。同じ付与リストで支出も制御できます。所有するすべてのモデルを呼び出せる agent を1人につき割り当てると、人数分の請求が発生します。そのため、10個の agent を配布する前に、agent のモデル呼び出しへの支出上限を設定する方法を確認してください。

ゲートウェイがエージェントから鍵を遠ざける仕組み

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

デプロイ方法は、次の 2 つの仕組みで決まります。

  • HTTPS の傍受は中間者攻撃の構成になります。ゲートウェイがローカルの認証局を生成し、エージェントがそれを信頼します。その後、ゲートウェイはエージェントとの TLS 接続を終端し、upstream サービスに対して新しい接続を開きます。そのため、HTTP クライアントがゲートウェイの認証局を信頼しないエージェントでは、認証エラーではなく証明書検証エラーが発生します。
  • エージェントは Proxy-Authorization ヘッダーで自身を識別します。エージェントとゲートウェイが同じ内部 Docker ネットワークを共有する単一のホストでは、このヘッダーが自分の管理外のネットワークを通過することはありません。ホスト外のエージェントからゲートウェイに接続する場合は、VPN または TLS トランスポートで接続を保護してください。このヘッダーは bearer token であり、upstream は raw CONNECT プロキシポートに VPN を使用することを推奨しています。

率直なトレードオフとして、ゲートウェイは設計上、エージェントが送信するすべてのリクエストを平文で読み取ります。これはマシン上で最も機密性の高いプロセスです。ホストもそれに応じて管理し、最小権限の Linux ユーザーを使用してログインできる人数を少なく保ってください。

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

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

この設計は sandbox ネットワークで効果を発揮します。compose ファイルでは、internal: true とマークされた 2 つ目のネットワークを定義しています。Docker では、これは外部ネットワーク接続がないことを意味します。Sandbox はこのネットワークに参加します。Gateway は両方のネットワークに接続されているため、外部への唯一の経路になります。Runner のドキュメントには、その目的が明確に記載されています。「Gateway が両方のネットワークに接続された internal ネットワークによって、Gateway 経由の外向き通信だけが単なる推奨ではなく、境界として機能する」。Agent は外部アドレスへの直接接続を開いて Gateway を迂回できません。許可するリクエストは、引き続き Gateway のポリシーによって決まります。

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

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

"Internal": true と表示されるはずです。false と表示される場合、外向き通信の制御が無効になっており、Gateway は再び単なる推奨になっています。docker network ls に表示された sandbox ネットワーク名を使用してください。onecli-sandboxes はデフォルト値にすぎません。

OneCLI のサンドボックスはどの程度強固か

このセクションはゆっくり読んでください。「sandboxed」という表現はプロジェクト自身の説明では大きな意味を持ちますが、その仕組みは runner のドキュメントと backend のコードに記載されています。

README では、各 agent に「ファイルシステムと shell を備えた独自の分離サンドボックス」が割り当てられ、Sandbox Supervisor は「各サンドボックス内で動作し、vendor-neutral な harness interface を介して agent runtime を交換可能にする」コンポーネントだと説明されています。ただし、どのような仕組みで分離しているかは、どちらの文にも書かれていません。runner のドキュメントには記載があります。デフォルトの backend は Docker (RUNNER_BACKEND=docker) であり、サンドボックスはメモリ上限、CPU 上限、プロセス数上限を設定し、内部ネットワークに接続した Docker コンテナです。コードには、他の backend に対応するための接続点があります。現在の runner のコードには Kubernetes backend も実装されており、Helm chart はサンドボックス用の Job と永続ボリュームにこれを使用します。このガイドの Compose インストールでは、サンドボックスは Docker コンテナです。

runner のドキュメントでは、現在 Docker の境界が説明されています。agent は node として実行され、no-new-privileges が適用され、Linux capabilities はすべて削除され、Docker のデフォルト seccomp プロファイルが使用されます。backend がサンドボックスにマウントするのは、agent の永続 home だけです。したがって、ここでは狭い意味で解釈してください。上限はリソース制限です。内部ネットワークは実際の外向き通信制御です。agent とホストの分離にはこれらのコンテナ制御が使われますが、コンテナはホストの kernel を共有します。

もう 1 つ考慮すべき事実があります。runner service は /var/run/docker.sock をマウントします。これは、サンドボックスを作成する方法だからです。rootful Docker daemon の socket にアクセスできることは、ホスト上の root 権限と同等です。その API を呼び出せるユーザーは、ホストのファイルシステムをコンテナ内にマウントして起動できるためです。提供される Docker backend の runner は、この socket を使用します。その結果、runner process も gateway と同じように機密性の高いコンポーネントになります。SSH terminator もサンドボックスコンテナ内で exec するために同じ socket をマウントします。compose file 自身のコメントでも、このマウントはホスト上で root 権限と同等だと説明されています。そのため、開放する理由がない限り、port 10257 は loopback に限定してください。

共有 kernel の境界は、保守的に扱ってください。実際には、次の 3 つを習慣にします。

  1. OneCLI は、それ以外の処理を行わないマシンで実行します。無関係な本番サービス、共有データベース、他チームのデータを同じマシンに置かないでください。
  2. サンドボックス内で任意のコード実行権限を得た agent は、ホストに到達できる可能性があると想定します。その結果が発生しても復旧できるように、バックアップはマシン外に保管します。
  3. agent が隔離されていると同僚に説明する前に、apps/runner/src を読むか、upstream に確認してください。

文書化された境界の説明と、upstream に確認する価値のある質問を確認するには、実際の agent サンドボックス境界の様子 と比較してください。重要なのは、文書化された仕組みが、阻止する必要のある脅威を実際に対象としているかどうかです。

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

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 つのファイル

アップグレードでは、サービスイメージと分離されたエージェントイメージを更新し、実行中のサンドボックスを再起動する必要があります。ワンショットの migration サービスは、すべての up で API の前に実行されます。migration に失敗すると、未完了のスキーマを使ってサービスを提供するのではなく、stack は起動を拒否します。これは望ましい動作です。アップグレードの失敗が、気付かない破損ではなく停止として現れるためです。docker compose logs migrations にその理由が示されています。

見落としやすい手順が 1 つあります。セルフホスティングのドキュメントでは、単独の docker compose pull && docker compose up -d を使ってアップグレードしないよう警告しています。エージェントのサンドボックスイメージは Compose サービスではないためです。これは runner 上の RUNNER_AGENT_IMAGE の値です。そのため docker compose pull では検出されず、ホスト型エージェントが警告なしに古いサンドボックスイメージを使い続ける可能性があります。checkout を更新して pin を変更し、文書化されたアップグレードツールを実行します。このツールがサンドボックスイメージを pull し、実行中のサンドボックスを再起動します。

cd onecli
git pull
sed -i 's/^ONECLI_VERSION=.*/ONECLI_VERSION=2.17.0/' docker/.env
pnpm install
pnpm run setup --upgrade
cd docker
docker compose logs migrations

2.17.0 を、移行先の release に置き換えます。サンドボックスを再起動すると実行中の処理が中断されます。各エージェントの永続 workspace は保持されます。

install script でインストールした場合は、手動で pull せずにその script を再実行してください。これにより、compose file と参照先イメージの状態が一致します。特定の release を指定する場合は、先に ONECLI_VERSION を export します。script は、.env file だけに保持された pin を上書きするためです。

database、configuration、agent workspace の volume をバックアップします。PostgreSQL には、エージェント、conversation、memory、暗号化された secret が保存されます。docker/.env file には SECRET_ENCRYPTION_KEY が保存されています。この key がなければ、database の他の部分を復元しても暗号化された secret は読み取れません。各エージェントの /workspace は別の永続 volume に保存されるため、それぞれ個別にバックアップする必要があります。

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

これらのコピーと workspace のバックアップは、同じホスト上に保管しないでください。必要な手順は、stateful な Compose stack と同じです。すでに定期的に Docker Compose stack をバックアップしてアップグレード している場合は、database、configuration、workspace の volume を対象に追加して、あとは運用を意識せずに済むようにします。

動作しない場合

  • スタックが healthy にならず、docker compose up -d --wait が非ゼロの終了コードで終了する場合は、まず docker compose logs migrations を確認します。API は意図的にこのサービスの起動を待機するためです。
  • エージェントがアイドル状態のままで、sandbox が作成されない場合は、COMPOSE_PROFILES=runner が docker/.env に含まれていることと、docker compose ps に runner が表示されることを確認します。次に、エージェントにモデルキーが付与されていることを確認します。モデルキーがないと sandbox は起動しません。
  • 空きスロットがない場合、RUNNER_MAX_SANDBOXES のデフォルト値は 4 です。バックグラウンドプロセスが実行中の sandbox は、保持時間の上限に達して排除されるまでスロットを占有します。docker ps で実際に稼働しているものを確認できます。
  • スタックが起動せず、Docker がポートの使用中を報告する場合は、runner プロファイルを有効にすると、SSH の入口に 10257 も必要になることを確認します。ほかの 4 つのポートも必要です。
  • コンテナが消える、またはホストの処理が極端に遅くなる場合は、dmesg -T | grep -i oom でメモリ不足を確認します。デフォルトのメモリ上限では、1 つの sandbox が最大 2048 MB を使用できます。
  • エージェントの HTTPS 呼び出しが、認証エラーではなく証明書検証エラーで失敗する場合は、エージェントの HTTP クライアントがゲートウェイの認証局を信頼していません。
  • エージェントを削除した後も古いコンテナやボリュームが残る場合があります。runner は 60 秒ごとに状態を調整し、RUNNER_ORPHAN_GRACE_SECONDS より古い孤立リソースを削除します。RUNNER_ORPHAN_GRACE_SECONDS のデフォルト値は 3600 です。リークと判断する前に 1 時間待ってください。

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

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

個人で使う場合、得られるものに対して仕組みが過剰です。自分専用の agent を1つ動かすために PostgreSQL、control plane、gateway、runner を稼働させることになりますが、gateway が解決する credential の問題は、key の保有者が自分だけならほとんど発生しません。代わりに、小規模なマシンで単一の harness を実行してください。VPS 上の単一 agent harness で同じ役割を、はるかに少ないメモリで実現できます。まだ方向性をまったく決めていない場合は、self-hosted AI agent の比較 にある調査から始めるほうが低コストです。agent 自体が不慣れで、実行するサーバーが問題なのではない場合は、まず agent の実際の動作を学ぶ段階的な手順 に沿って進めてください。tool call と memory store の実際の役割を理解すれば、各自の agent にどの grant を与えるべきか判断できるためです。

FAQ

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

Compose plugin 2.24.0 以降を備えた Docker、この手順で使用するセットアップウィザード向けの Node.js と pnpm、および十分なメモリが必要です。PostgreSQL は compose file に含まれるため、個別にインストールする必要はありません。計画を左右するのはメモリです。runner は各 agent sandbox の上限をデフォルトで 2048 MB に設定しており、ドキュメントでは、デフォルトの 4 sandbox を稼働させるために、基本スタックとは別に約 10 GiB の空き容量を求めています。chart が想定する基本スタックの予算を 2 GB とした場合、4 GB のサーバーでは上限いっぱいの sandbox を 1 つ、16 GB のサーバーではデフォルトの同時実行上限を収容できます。これらは計画用の数値であり、実測に基づく最小要件や固定のメモリ割り当てではありません。

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

PostgreSQL が必要です。DATABASE_URL は PostgreSQL の接続文字列として記載されており、提供される compose file は pgdata volume を使用して postgres:18-alpine を起動します。また、API の起動前に別の migrations service が schema を適用します。SQLite のオプションは記載されていません。外部の PostgreSQL サーバーを使用する場合は、API と migrations service の両方がそのサーバーを使用するように設定します。提供される compose file では、両方の接続文字列が組み込みの PostgreSQL service に設定されています。

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

文書化されている Compose の仕組みでは、メモリ、CPU、プロセス数に上限を設定した Docker container を使用します。この container は internal: true とマークされた network に接続されるため、外部トラフィックは gateway を経由します。egress 制御は実際に機能し、docker network inspect で確認できます。agent は node として実行され、no-new-privileges が設定されます。Linux capabilities はすべて削除され、Docker のデフォルト seccomp profile も使用されますが、host kernel は共有します。runner と SSH terminator はどちらも /var/run/docker.sock を mount します。これは、rootful Docker daemon を使用する host 上では root と同等の権限です。OneCLI は専用のサーバーで実行し、バックアップはそのサーバーの外部に保管してください。

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

いいえ。runner は outbound-only で、外部から到達できる port を保持しないため、tunnel なしで NAT の背後でも動作します。compose file はデフォルトで dashboard、gateway、API、PostgreSQL、および runner profile 下の SSH front door(10257)を 127.0.0.1 に bind します。dashboard には SSH tunnel 経由で接続してください。複数の利用者が必要な場合は、upstream の reverse proxy 設定で TLS と、dashboard、API、gateway に必要な route を構成します。ただし、到達可能な全員に registration が開かれたままである点に注意してください。10255 の gateway は agent 用です。1 台のサーバー構成では、agent は内部の Docker network 経由でそこへ接続します。

OneCLI は社内で無料で使用できますか?

core は Apache-2.0 で提供され、セルフホストによる本番利用に commercial licence は必要ありません。ee/ という名前の directory には OneCLI Enterprise License が適用されます。このライセンスは開発、テスト、評価では無料ですが、本番では subscription が必要です。対象範囲は release 間で変わります。2026 年 8 月 18 日付の v2.0.1 notes には、GitHub で検出可能な Apache-2.0 licence file の復元が記載されています。そのため、単一の機能を前提に workflow を構築する前に、デプロイする正確な tag の LICENSE と ee/ directory を確認してください。

この記事は役に立ちましたか?