Exécuter Codex avec un répertoire personnel sur NFS

Configurez un répertoire personnel Codex partagé pour travailler de manière interactive sur plusieurs hôtes Linux.

Lorsque des hôtes Linux partagent un répertoire personnel Codex (~/.codex par défaut) via Network File System (NFS), ils peuvent corrompre une base de données SQLite s’ils l’ouvrent simultanément en mode de journalisation anticipée (WAL). Pour travailler de manière interactive dans la CLI ou dans l’application Codex via SSH, faites migrer le répertoire personnel partagé. Pour les tâches par lots indépendantes, conservez le répertoire personnel Codex ou le répertoire SQLite de chaque hôte sur un disque local.

Pourquoi NFS peut perturber SQLite

L’application Codex et l’interface du terminal utilisent un index SQLite pour répertorier les conversations. Les bases de données stockent également les objectifs et l’état du traitement de la mémoire. Sur un disque local, Codex utilise normalement le mode WAL. Les processus exécutés sur des hôtes différents ne peuvent pas partager la mémoire nécessaire à WAL.

Lorsque Codex détecte NFS sous Linux, il crée les bases de données en mode de journal de restauration (DELETE), qui utilise des verrous de fichiers à la place. Faites migrer les bases de données WAL existantes avant de les ouvrir depuis un autre hôte.

Codex enregistre également les événements des conversations dans des fichiers rollout-*.jsonl. Ceux-ci peuvent déjà résider sur NFS, car un seul processus à la fois écrit dans chaque fichier de déroulement de session. La migration de SQLite laisse ces fichiers en place.

Faire migrer un répertoire personnel NFS existant

1. Vérifier le répertoire personnel partagé

Exécutez codex --version sur chaque hôte, y compris sur tout backend SSH. Utilisez une version qui inclut codex migrate-nfs-db, comme Codex CLI 0.166.0. Vérifiez que tous les hôtes utilisant ce répertoire personnel partagé utilisent le même répertoire SQLite. Demandez à votre administrateur du stockage de vérifier qu’un verrou de fichier détenu sur un hôte bloque un verrou incompatible sur l’autre. Conservez SQLite en local si le montage ne le permet pas.

2. Arrêter Codex sur tous les hôtes

En mode démon, la CLI se connecte à un serveur en arrière-plan qui continue de fonctionner entre les sessions. Son socket Unix ne fonctionne que sur l’hôte qui l’a démarré. Nous recommandons d’exécuter la CLI sans le démon lorsque des hôtes partagent un répertoire personnel Codex via NFS. Arrêtez le démon sur chaque hôte qui l’exécute avec codex app-server daemon stop.

Pour empêcher la CLI de le redémarrer, définissez daemon_auto_start sur false sous [features] dans votre config.toml partagé.

[features]
daemon_auto_start = false

Pour une seule session CLI, passez --no-daemon. Cette option permet également de contourner un démon déjà en cours d’exécution.

3. Exécuter la migration

Exécutez la migration sur un seul hôte Linux par répertoire personnel Codex partagé. Utilisez le compte du propriétaire du répertoire personnel et sa configuration habituelle. Laissez Codex à l’arrêt sur les autres hôtes jusqu’à la fin de la migration.

codex migrate-nfs-db

4. Reprendre une conversation

Si la commande indique Skipped logs database, vérifiez son emplacement. Une base de données de journaux située sur un disque local ne nécessite aucune autre action. Si elle se trouve sur NFS, vérifiez qu’elle utilise le mode de journalisation DELETE ou déplacez-la sur un disque local avant de rouvrir Codex sur un autre hôte.

Une fois la migration réussie, ouvrez le même projet sur un autre hôte avec le même compte utilisateur. Reprenez une conversation que vous connaissez dans l’application ou exécutez codex --no-daemon resume. Vérifiez que votre dernier échange est présent et que vous pouvez poursuivre la conversation.

Déplacer les journaux de diagnostic sur un disque local

Facultatif, recommandé après la migration. Les journaux de diagnostic vous aident à analyser les erreurs et les démarrages lents. Les écrire en local réduit le trafic sur NFS.

Créez un répertoire de journaux privé et accessible en écriture sur chaque hôte. Définissez log_dir dans le config.toml de l’utilisateur sur le chemin absolu propre à cet utilisateur. Par exemple, Alice pourrait utiliser ce paramètre.

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

Les nouveaux journaux sont enregistrés dans ce répertoire. Les anciens restent en place.

Imposer le mode de journalisation à l’ensemble d’un parc

Arrêtez d’abord tous les clients sur chaque hôte qui utilise un répertoire personnel concerné. Le paramètre porte le nom unsafe, car convertir une base de données pendant qu’un autre hôte y écrit peut la corrompre.

Une fois les clients arrêtés, ajoutez ce paramètre à la configuration gérée des hôtes dans /etc/codex/requirements.toml.

unsafe_enforce_sqlite_journal_mode = true

Le paramètre s’applique à tous les utilisateurs des hôtes configurés. La prochaine fois qu’un utilisateur ouvre Codex, celui-ci fait automatiquement migrer les bases de données WAL existantes au moment de les ouvrir en écriture sur NFS. Pour chaque répertoire personnel partagé, laissez la migration se terminer sur un hôte avant de reconnecter les autres. Si la migration échoue, laissez les autres clients à l’arrêt et suivez les étapes de récupération.

Exécuter des tâches par lots indépendantes

Si une tâche sans surveillance n’a pas besoin de l’historique de vos sessions interactives, exécutez codex exec avec un répertoire personnel Codex situé sur le disque local du nœud d’exécution. Si les fichiers de session doivent rester sur NFS, définissez CODEX_SQLITE_HOME sur un répertoire local privé pour chaque tâche afin que les nœuds d’exécution ne se disputent pas l’accès à la même base de données.

  • Conserver une trace de la conversation. Attribuez à chaque tâche un CODEX_HOME privé et persistant pour son fichier de déroulement de session, ainsi qu’un CODEX_SQLITE_HOME privé et local à l’hôte pour sa base de données. L’index du nœud d’exécution est distinct de votre index interactif. Conservez le fichier de déroulement de session sous $CODEX_HOME/sessions/ si vous devez inspecter la tâche après l’arrêt du nœud d’exécution.
  • Conserver uniquement le résultat. Placez le répertoire personnel de la tâche sur un disque local et exécutez codex exec --ephemeral. Cette commande n’enregistre pas de session pouvant être reprise. Utilisez -o pour écrire la réponse finale dans un fichier persistant ou --json pour transmettre les événements en continu à votre exécuteur de tâches.

Pour une tâche qui nécessite un fichier de déroulement de session, faites créer les deux répertoires par le planificateur et faites-lui fournir l’authentification et la configuration du répertoire personnel de la tâche. Remplacez les chemins de l’exemple par le répertoire personnel Codex persistant de cette tâche et le répertoire SQLite local au nœud d’exécution. Un paramètre sqlite_home géré ou configuré est prioritaire sur 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."

Questions fréquentes

Comment savoir si une erreur est liée à NFS ?

Une erreur de migration telle que cannot open source database exclusively signifie que Codex n’a pas pu verrouiller la base de données. Un autre client peut également provoquer cette erreur sur un disque local. Sous Linux, exécutez findmnt -T "$DB_PATH" avec le chemin de la base de données concernée. Si la commande indique nfs ou nfs4, recherchez les processus qui écrivent sur tous les hôtes et demandez à l’administrateur du stockage de vérifier le verrouillage entre hôtes sur ce montage. Arrêtez les clients restants avant de réessayer.

Que dois-je vérifier dans la sortie de la migration ?

Pour chaque base de données, Codex affiche Migrated database: et WAL backup:, ou Already in DELETE mode:. Si vous utilisez des autorisations de groupe ou des règles d’accès étendues, vérifiez-les après la migration et avant de rouvrir les clients.

Si log_dir était déjà défini, la commande ignore la base de données des journaux. Avant de partager cette base de données entre plusieurs hôtes, assurez-vous qu’elle utilise DELETE ou conservez-la sur un disque local.

Si vous voyez No databases found., vérifiez le répertoire SQLite effectif de l’utilisateur propriétaire du répertoire personnel. Si l’espace de stockage temporaire local est insuffisant, choisissez un répertoire local à l’hôte disposant d’assez d’espace et passez son chemin absolu avec --staging-dir.

Comment récupérer les données après l’échec d’une migration ?

Laissez les autres clients à l’arrêt. Conservez le message d’erreur exact, le chemin de la base de données et le chemin de sauvegarde affiché. Certaines bases de données peuvent avoir déjà migré. Conservez la base de données d’origine et ses fichiers annexes ensemble dans leur répertoire de sauvegarde. Après avoir résolu une erreur de verrouillage ou d’espace, réexécutez codex migrate-nfs-db sur le même hôte. En cas d’erreur d’intégrité ou de remplacement manquant, travaillez à partir de copies avant de restaurer quoi que ce soit. Les fichiers de déroulement de session peuvent aider à reconstituer l’historique des conversations. La récupération de l’état stocké uniquement dans SQLite, y compris les objectifs, nécessite une base de données intacte.

Avant de démarrer une session CLI distincte, vérifiez que les paramètres de stockage gérés ne redirigeront pas les écritures vers le répertoire personnel concerné. Démarrez ensuite Codex avec un répertoire temporaire sur un disque local. Le nouveau répertoire personnel peut nécessiter une connexion.

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."