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 파일에도 저장합니다. 각 롤아웃은 한 번에 하나의 프로세스만 기록하므로 이러한 파일은 이미 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 홈마다 Linux 호스트 한 대에서만 마이그레이션을 실행하세요. 홈 소유자의 계정과 평소 사용하는 구성을 사용하세요. 마이그레이션이 끝날 때까지 다른 호스트에서는 Codex를 중지한 상태로 유지하세요.

codex migrate-nfs-db

4. 대화 재개하기

명령이 Skipped logs database을 보고하면 해당 위치를 확인하세요. 로컬 디스크에 있는 로그 데이터베이스에는 추가 조치가 필요하지 않습니다. NFS에 있다면 다른 호스트에서 Codex를 다시 열기 전에 DELETE 저널 모드를 사용하는지 확인하거나 로컬 디스크로 옮기세요.

마이그레이션이 성공하면 다른 호스트에서 동일한 사용자로 같은 프로젝트를 여세요. 앱에서 기존 대화를 재개하거나 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 데이터베이스를 쓰기용으로 열 때 자동으로 마이그레이션합니다. 각 공유 홈에서 한 호스트의 마이그레이션이 완료된 후 다른 호스트를 다시 연결하세요. 마이그레이션이 실패하면 다른 클라이언트를 중지한 상태로 두고 복구 단계를 따르세요.

독립적인 배치 작업 실행하기

무인 작업에 대화형 세션 기록이 필요하지 않다면 워커의 로컬 디스크에 있는 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."