Ejecuta Codex con un directorio de inicio en NFS
Configura un directorio de inicio compartido de Codex para el trabajo interactivo entre hosts Linux.
Cuando los hosts Linux comparten un directorio de inicio de Codex (~/.codex de forma predeterminada) mediante Network File System (NFS), pueden dañar una base de datos SQLite si la abren en modo de registro de escritura anticipada (WAL) al mismo tiempo. Para el trabajo interactivo en la CLI o en la aplicación Codex mediante SSH, migra el directorio de inicio compartido. Para los trabajos por lotes independientes, mantén el directorio de inicio de Codex o el directorio de SQLite de cada host en un disco local.
Por qué NFS puede provocar fallos en SQLite
La aplicación Codex y la interfaz de terminal usan un índice SQLite para mostrar las conversaciones. Las bases de datos también almacenan los objetivos y el estado del procesamiento de memoria. En un disco local, Codex normalmente usa el modo WAL. Los procesos de distintos hosts no pueden compartir la memoria que necesita WAL.
Cuando Codex detecta NFS en Linux, crea las bases de datos en modo de diario de reversión (DELETE), que usa bloqueos de archivos en su lugar. Migra las bases de datos WAL existentes antes de abrirlas desde otro host.
Codex también guarda los eventos de conversación en archivos rollout-*.jsonl. Estos ya pueden residir en NFS porque solo un proceso escribe cada registro de sesión a la vez. La migración de SQLite deja esos archivos en su ubicación.
Migra un directorio de inicio existente en NFS
1. Comprueba el directorio de inicio compartido
Ejecuta codex --version en cada host, incluido cualquier backend SSH. Usa una compilación que incluya codex migrate-nfs-db, como Codex CLI 0.166.0. Confirma que todos los hosts que usan este directorio de inicio compartido usan el mismo directorio de SQLite. Pide a tu administrador de almacenamiento que verifique que un bloqueo de archivo mantenido en un host impide un bloqueo incompatible en el otro. Mantén SQLite en un disco local si el montaje no permite hacerlo.
2. Detén Codex en todos los hosts
En el modo demonio, la CLI se conecta a un servidor en segundo plano que sigue ejecutándose entre sesiones. Su socket Unix solo funciona en el host que lo inició. Recomendamos ejecutar la CLI sin el demonio cuando los hosts comparten un directorio de inicio de Codex mediante NFS. Detén el demonio en cada host que lo ejecute con codex app-server daemon stop.
Para evitar que la CLI vuelva a iniciarlo, establece daemon_auto_start en false bajo [features] en tu config.toml compartido.
[features]
daemon_auto_start = falsePara una sola sesión de la CLI, pasa --no-daemon. Esta opción también omite un demonio que ya esté en ejecución.
3. Ejecuta la migración
Ejecuta la migración en un único host Linux por cada directorio de inicio compartido de Codex. Usa la cuenta del propietario del directorio de inicio y su configuración habitual. Mantén Codex detenido en los demás hosts hasta que termine la migración.
codex migrate-nfs-db4. Reanuda una conversación
Si el comando informa de Skipped logs database, comprueba su ubicación. Una base de datos de registros en un disco local no requiere ninguna otra acción. Si está en NFS, confirma que usa el modo de diario DELETE o muévela a un disco local antes de volver a abrir Codex en otro host.
Cuando la migración finalice correctamente, abre el mismo proyecto en otro host con el mismo usuario. Reanuda una conversación conocida en la aplicación o ejecuta codex --no-daemon resume. Comprueba que aparece tu último turno y que puedes continuar la conversación.
Mueve los registros de diagnóstico a un disco local
Opcional; recomendado después de la migración. Los registros de diagnóstico te ayudan a investigar errores e inicios lentos. Escribirlos localmente reduce el tráfico en NFS.
Crea un directorio de registros privado y con permisos de escritura en cada host. Establece log_dir en el config.toml del usuario con la ruta absoluta correspondiente a ese usuario. Por ejemplo, Alice podría usar esta configuración.
log_dir = "/var/local/codex/alice/logs"Los nuevos registros se guardan en ese directorio. Los registros anteriores permanecen en su ubicación.
Aplica el modo de diario en una flota de hosts
Primero detén todos los clientes en cada host que use un directorio de inicio afectado. El ajuste se llama unsafe porque convertir una base de datos mientras otro host escribe en ella puede dañarla.
Con los clientes detenidos, añade este ajuste a la configuración administrada de los hosts en /etc/codex/requirements.toml.
unsafe_enforce_sqlite_journal_mode = trueEl ajuste se aplica a todos los usuarios de los hosts configurados. La próxima vez que un usuario abra Codex, este migrará automáticamente las bases de datos WAL existentes al abrirlas para escritura en NFS. Para cada directorio de inicio compartido, deja que la migración termine en un host antes de volver a conectar los demás. Si la migración falla, mantén los demás clientes detenidos y sigue los pasos de recuperación.
Ejecuta trabajos por lotes independientes
Si un trabajo desatendido no necesita el historial de tus sesiones interactivas, ejecuta codex exec con un directorio de inicio de Codex en el disco local del proceso de trabajo. Si los archivos de sesión deben permanecer en NFS, establece CODEX_SQLITE_HOME en un directorio local privado para cada trabajo, de modo que los procesos de trabajo no compitan por la misma base de datos.
- Conserva un registro de la conversación. Asigna a cada trabajo un
CODEX_HOMEprivado y persistente para su registro de sesión y unCODEX_SQLITE_HOMEprivado y local al host para su base de datos. El índice del proceso de trabajo está separado de tu índice interactivo. Mantén el registro de sesión bajo$CODEX_HOME/sessions/si necesitas inspeccionar el trabajo después de que finalice el proceso de trabajo. - Conserva solo el resultado. Coloca el directorio de inicio del trabajo en un disco local y ejecuta
codex exec --ephemeral. Esto omite el guardado de una sesión que se pueda reanudar. Usa-opara escribir la respuesta final en un archivo persistente o--jsonpara transmitir eventos a tu ejecutor de trabajos.
Para un trabajo que necesite un registro de sesión, configura el programador para que cree ambos directorios y proporcione la autenticación y la configuración del directorio de inicio del trabajo. Sustituye las rutas de ejemplo por el directorio de inicio persistente de Codex de este trabajo y el directorio de SQLite local al host del proceso de trabajo. Un sqlite_home administrado o configurado tiene prioridad sobre 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."Preguntas frecuentes
¿Cómo puedo saber si un error está relacionado con NFS?
Un error de migración como cannot open source database exclusively significa que Codex no pudo bloquear la base de datos. Otro cliente también puede provocar esto en un disco local. En Linux, ejecuta findmnt -T "$DB_PATH" con la ruta a la base de datos afectada. Si informa de nfs o nfs4, comprueba si hay procesos de escritura en todos los hosts y pide al administrador de almacenamiento que verifique el bloqueo entre hosts en ese montaje. Detén los clientes restantes antes de volver a intentarlo.
¿Qué debo buscar en la salida de la migración?
Para cada base de datos, Codex muestra Migrated database: y WAL backup:, o Already in DELETE mode:. Si dependes de permisos de grupo o reglas de acceso extendidas, verifícalos después de la migración y antes de volver a abrir los clientes.
Si log_dir ya estaba establecido, el comando omite la base de datos de registros. Antes de compartir esa base de datos entre hosts, asegúrate de que usa DELETE o mantenla en un disco local.
Si ves No databases found., comprueba el directorio efectivo de SQLite del usuario propietario del directorio de inicio. Si no hay suficiente espacio local para los archivos temporales, elige un directorio local al host con espacio suficiente y pasa su ruta absoluta con --staging-dir.
¿Cómo me recupero después de una migración fallida?
Mantén los demás clientes detenidos. Guarda el error exacto, la ruta de la base de datos y la ruta de la copia de seguridad que se muestra. Puede que algunas bases de datos ya se hayan migrado. Mantén la base de datos original y sus archivos auxiliares juntos en su directorio de copia de seguridad. Tras resolver un error de bloqueo o de espacio, vuelve a ejecutar codex migrate-nfs-db en el mismo host. Si hay un error de integridad o falta un archivo de reemplazo, trabaja a partir de copias antes de restaurar nada. Los registros de sesión pueden ayudar a reconstruir el historial de conversaciones. Recuperar el estado almacenado únicamente en SQLite, incluidos los objetivos, requiere una base de datos intacta.
Antes de iniciar una sesión independiente de la CLI, confirma que los ajustes de almacenamiento administrados no redirigirán las escrituras al directorio de inicio afectado. Después, inicia Codex usando un directorio temporal en un disco local. Puede que el nuevo directorio de inicio requiera iniciar sesión.
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."