NFS ホームディレクトリで Codex を実行する

Linux ホスト間で対話的な作業を行うために、共有の Codex ホームを設定します。

Linux ホストが Network File System (NFS) 経由で Codex ホーム(デフォルトは ~/.codex)を共有している場合、SQLite データベースを同時に先行書き込みログ (WAL) モードで開くと、データベースが破損する可能性があります。CLI または SSH 経由の Codex アプリ で対話的な作業を行う場合は、共有ホームを移行してください。独立したバッチジョブでは、各ホストの Codex ホームまたは SQLite ディレクトリをローカルディスクに配置してください。

NFS で SQLite が破損する理由

Codex アプリ とターミナル UI は、会話を一覧表示するために SQLite インデックスを使用します。データベースには、目標やメモリ処理の状態も保存されます。ローカルディスクでは、Codex は通常 WAL モードを使用します。異なるホスト上のプロセス間では、WAL が必要とするメモリを共有できません。

Codex は Linux の NFS を検出すると、代わりにファイルロックを使うロールバックジャーナルモード(DELETE)でデータベースを作成します。既存の WAL データベースは、別のホストから開く前に移行してください。

Codex は会話のイベントを rollout-*.jsonl ファイルにも保存します。各ロールアウトへの書き込みは一度に 1 つのプロセスが行うため、これらのファイルはそのまま NFS 上に配置できます。SQLite を移行しても、これらのファイルの場所は変わりません。

既存の NFS ホームを移行する

1. 共有ホームを確認する

SSH バックエンドを含む各ホストで codex --version を実行してください。Codex CLI 0.166.0 など、codex migrate-nfs-db を含むビルドを使用します。この共有ホームを使うすべてのホストが、同じ SQLite ディレクトリを使用していることを確認してください。あるホストが保持するファイルロックによって、別のホストの競合するロックがブロックされることを、ストレージ管理者に確認してもらいます。マウントがこれに対応できない場合は、SQLite をローカルに配置してください。

2. すべてのホストで Codex を停止する

デーモンモードでは、CLI はセッション間も稼働し続けるバックグラウンドサーバーに接続します。その Unix ソケットは、サーバーを起動したホストでのみ機能します。NFS 経由で Codex ホームを共有する場合は、デーモンを使わずに CLI を実行することをおすすめします。デーモンを実行している各ホストで、codex app-server daemon stop を使って停止してください。

CLI がデーモンを再び起動しないようにするには、共有の config.toml の [features] 内で、daemon_auto_start を false に設定します。

[features]
daemon_auto_start = false

単一の CLI セッションでは、--no-daemon を渡してください。このフラグは、すでに実行中のデーモンもバイパスします。

3. 移行を実行する

共有 Codex ホームごとに、1 台の Linux ホストだけで移行を実行してください。ホーム所有者のアカウントと通常の設定を使用します。移行が完了するまで、他のホストでは Codex を停止したままにしてください。

codex migrate-nfs-db

4. 会話を再開する

コマンドが Skipped logs database を報告した場合は、その場所を確認してください。ログデータベースがローカルディスクにある場合、追加の操作は不要です。NFS 上にある場合は、ジャーナルモードが DELETE であることを確認するか、ローカルディスクに移動してから、別のホストで Codex を再び開いてください。

移行が成功したら、別のホストで同じユーザーとして同じプロジェクトを開きます。アプリで以前の会話を再開するか、codex --no-daemon resume を実行してください。最後のターンが表示され、会話を続けられることを確認します。

診断ログをローカルディスクに移動する

省略可能ですが、移行後の実施をおすすめします。 診断ログは、エラーや起動の遅さを調査する際に役立ちます。ローカルに書き込むことで、NFS 上のトラフィックを減らせます。

各ホストに、非公開で書き込み可能なログディレクトリを作成してください。ユーザーの config.toml 内で、log_dir をそのユーザー用の絶対パスに設定します。たとえば、Alice は次の設定を使用できます。

log_dir = "/var/local/codex/alice/logs"

新しいログは、そのディレクトリに保存されます。古いログは元の場所に残ります。

複数のホスト全体にジャーナルモードを適用する

まず、対象のホームを使用するすべてのホストで、すべてのクライアントを停止してください。この設定が unsafe という名前なのは、別のホストが書き込み中にデータベースを変換すると、破損する可能性があるためです。

クライアントを停止した状態で、ホストの /etc/codex/requirements.toml にある管理対象の設定に、次の設定を追加します。

unsafe_enforce_sqlite_journal_mode = true

この設定は、設定済みホスト上のすべてのユーザーに適用されます。ユーザーが次に Codex を開くと、NFS 上の既存の WAL データベースを書き込み用に開く際に、自動的に移行されます。共有ホームごとに、1 台のホストで移行が完了してから、他のホストを再接続してください。移行に失敗した場合は、他のクライアントを停止したままにして、復旧手順に従ってください。

独立したバッチジョブを実行する

無人実行のジョブで対話型セッションの履歴が不要な場合は、ワーカーのローカルディスクに Codex ホームを配置して codex exec を実行してください。セッションファイルを NFS 上に保持する必要がある場合は、CODEX_SQLITE_HOME をジョブごとに専用のローカルディレクトリに設定し、ワーカー間で同じデータベースが競合しないようにします。

  • 会話の記録を保持する。 各ジョブに、ロールアウト用の専用かつ永続的な CODEX_HOME と、データベース用の専用かつホストローカルな CODEX_SQLITE_HOME を用意します。ワーカーのインデックスは、対話型のインデックスとは別になります。ワーカーの終了後にジョブを確認する必要がある場合は、ロールアウトを $CODEX_HOME/sessions/ 配下に保持してください。
  • 結果だけを保持する。 ジョブのホームをローカルディスクに配置し、codex exec --ephemeral を実行します。再開可能なセッションの保存はスキップされます。-o を使って最終応答を永続的なファイルに書き込むか、--json を使ってジョブランナーにイベントをストリーミングしてください。

ロールアウトが必要なジョブでは、スケジューラーに両方のディレクトリを作成させ、ジョブのホームに認証と設定を用意させます。例のパスを、このジョブ用の永続的な Codex ホームと、ワーカーのローカル SQLite ディレクトリに置き換えてください。管理対象または設定済みの sqlite_home は、CODEX_SQLITE_HOME よりも優先されます。

CODEX_HOME="/mnt/nfs/codex/jobs/job-1234" \
CODEX_SQLITE_HOME="/var/local/codex/jobs/job-1234" \
  codex exec "Summarize this repository's build steps."

よくある質問

エラーが NFS に関連しているかどうかは、どう判断できますか?

cannot open source database exclusively などの移行エラーは、Codex がデータベースをロックできなかったことを意味します。ローカルディスクでも、別のクライアントが原因で発生することがあります。Linux では、対象のデータベースへのパスを指定して findmnt -T "$DB_PATH" を実行してください。nfs または nfs4 が報告された場合は、すべてのホストで書き込み中のプロセスを確認し、そのマウントでホスト間のロックが機能することをストレージ管理者に確認してもらってください。再試行する前に、残りのクライアントを停止します。

移行の出力では、何を確認すればよいですか?

Codex は、データベースごとに Migrated database: と WAL backup:、または Already in DELETE mode: を出力します。グループ権限や拡張アクセスルールを利用している場合は、移行後、クライアントを再び開く前に、それらを確認してください。

log_dir がすでに設定されていた場合、コマンドはログデータベースをスキップします。そのデータベースをホスト間で共有する前に、DELETE を使用していることを確認するか、ローカルディスクに保持してください。

No databases found. が表示された場合は、ホームを所有するユーザーの実効 SQLite ディレクトリを確認してください。ローカルのステージング領域が不足している場合は、十分な空き容量があるホストローカルのディレクトリを選び、その絶対パスを --staging-dir で渡します。

移行に失敗した場合は、どう復旧すればよいですか?

他のクライアントは停止したままにしてください。正確なエラー、データベースのパス、出力されたバックアップのパスを保存します。一部のデータベースはすでに移行済みかもしれません。元のデータベースとそのサイドカーファイルは、バックアップディレクトリ内にまとめて保持してください。ロックや空き容量のエラーを解消したら、同じホストで codex migrate-nfs-db を再実行します。整合性エラーや置き換え後のファイルが見つからない場合は、何かを復元する前にコピーを使って作業してください。セッションのロールアウトは、会話履歴の再構築に役立ちます。目標を含む SQLite のみに保存された状態を復旧するには、破損していないデータベースが必要です。

別の CLI セッションを開始する前に、管理対象のストレージ設定によって、書き込み先が対象のホームに変更されないことを確認してください。その後、ローカルディスク上の一時ディレクトリを使って Codex を起動します。新しいホームでは、サインインが必要になる場合があります。

recovery_home=$(mktemp -d /tmp/codex-nfs-recovery.XXXXXXXX) &&
  CODEX_HOME="$recovery_home" CODEX_SQLITE_HOME="$recovery_home" \
  codex --no-daemon --sandbox read-only \
    "Help me recover a failed Codex NFS migration, run `$ codex doctor` to get the information about corrupted databases. Backup paths for databases should be in the original database with `_wal_migration_backup` in the end of the file. Ask user for the original error. Plan a recovery using copies and leave the originals untouched."