codexpi/docs/architecture.md

Architecture

CodexPi utilise quatre services applicatifs sur un réseau Compose privé.

Service	Rôle	Port conteneur	Publication hôte
nginx	reverse proxy unique	8080	0.0.0.0:8765 (LAN)
django-web	interface React, authentification et sessions Django	8001	aucune
api	FastAPI/Uvicorn, REST, WebSockets, terminal, Git, Docker, Codex	8000	aucune

nginx envoie /api/auth/*, /api/bootstrap et les fichiers de l'interface à Django. Les autres routes /api/* et /ws/* vont à FastAPI. FastAPI valide directement la session Django stockée en base et exige le jeton CSRF de la session pour les mutations et WebSockets.

Le frontend React est compilé dans l'image puis servi par Django. Les données persistantes sont dans ./data : base Django, base CodexPi, sessions JSONL et journal de sécurité. Le conteneur API monte uniquement la racine de projets autorisée, l'identité Codex existante et le socket Docker nécessaire à la page Docker. Le bind de /home/config utilise une propagation rslave : les supports montés sous cette racine sur l'hôte, y compris après le démarrage de l'API, deviennent visibles au même chemin dans le conteneur sans propager en retour les montages du conteneur vers l'hôte.

Le connecteur de machine distante ouvre uniquement des requêtes sortantes vers nginx. Les tâches list, read et write transitent par une file SQLite ; aucun terminal ni port entrant n'est exposé sur le PC associé.

Le bridge IA PC suit un modèle différent parce qu’OpenCode doit conserver le stream HTTP d’Ollama pendant l’inférence. Une association à usage unique enregistre l’adresse privée du PC et un jeton chiffré côté CodexPi. Le proxy Python du PC écoute sur le LAN, authentifie chaque requête et n’autorise que les routes Ollama de découverte et de génération ; l’API Ollama brute reste liée à 127.0.0.1. CodexPi produit sous data/local-ai/ un fichier OpenCode et un jeton privés, puis les transmet uniquement aux workers OpenCode. Un seul bridge est actif à la fois afin de rendre le routage et le modèle par défaut déterministes.

Les tâches Codex écrivent un flux JSONL persistant et peuvent reprendre après fermeture du navigateur. Le terminal utilise tmux lorsqu'il est disponible. Un projet est toujours identifié par UUID ; les chemins sont canonisés côté serveur et contrôlés contre les racines autorisées/interdites.

L’ordonnanceur autorise par défaut trois moteurs Codex simultanés pour trois projets distincts. Des verrous de fichiers partagés entre les workers imposent à la fois la capacité globale configurée par CODEXPI_MAX_CONCURRENT_AGENTS et l’exclusion mutuelle au niveau du projet. Les trois espaces globaux (Agent maître, Agent Raspberry Pi et Agent Bibliothécaire) restent des projets indépendants : leur marqueur réservé __global_agent__ sert uniquement à l’interface et ne crée pas de verrou partagé. Un groupe associe explicitement plusieurs projets locaux du même propriétaire grâce à la relation plusieurs-à-plusieurs project_group_members ; un projet peut donc participer à plusieurs groupes. Une tâche acquiert, dans un ordre stable, tous les verrous de ses groupes afin d’éviter les interblocages et les exécutions concurrentes sur une ressource partagée. Les chemins des autres membres sont injectés comme références de lecture pour Codex SAFE, sans être ajoutés aux racines d’écriture du sandbox, et les derniers comptes rendus alimentent un contexte commun asynchrone. Pour un projet en FULL ACCESS, ces chemins sont également injectés quel que soit le moteur avec une interdiction conversationnelle d’écrire ailleurs sans demande explicite ; le backend ne présente pas cette consigne comme une isolation, car le sandbox est désactivé. Les autres moteurs en SAFE ne reçoivent que les noms et comptes rendus. Ainsi, plusieurs projets indépendants avancent en parallèle et les membres d’un groupe restent sérialisés lorsqu’ils pilotent la même ressource.

Les orchestrations sont des machines à états persistantes dans SQLite. Les validations d’ébauche utilisent une empreinte de version ; les tests et la recette sont liés au commit vérifié. Une correction réutilise la discussion, la branche et le worktree existants. Une approbation est invalidée dès que la révision change.

Le chantier autonome de remédiation possède sa propre machine à états persistante (remediation_runs, remediation_step_runs, remediation_events, remediation_self_repairs). Un seul chantier peut être actif par propriétaire. Une boucle backend loue brièvement le chantier, attend la fin de la tâche courante, puis alterne agent projet et Agent maître. Le maître rend un verdict structuré approve, correct ou block; une correction réutilise la conversation du projet et le cycle est borné à trois reprises. Tout blocage est transmis à CodexPi (Self) dans une conversation persistante propre au chantier. La boucle surveille aussi cette tâche lorsque le chantier est BLOCKED; un verdict structuré fixed peut ajouter une précision bornée au prompt courant puis reprendre automatiquement le même fil, tandis que needs_user laisse le chantier bloqué avec une raison visible. Les auto-réparations sont bornées à trois incidents par chantier et leur relance de format à une tentative. Une reprise bloquée peut rebaser les textes du plan courant, mais le backend refuse toute modification du nombre, de l’ordre, de la cible ou du niveau de risque des étapes ; les conversations et preuves existantes sont conservées. Les étapes restent séquentielles pour respecter leurs dépendances, mais elles utilisent l’ordonnanceur normal : les autres projets et agents peuvent continuer en parallèle dans la limite globale. Le dernier état, les discussions, les auto-réparations et les événements survivent au redémarrage de l’API et à la fermeture de la PWA.

Le centre de coordination repose sur agent_decisions, agent_incidents, agent_runtime_policies, agent_project_policies, specialist_agents et specialist_delegations. À la fin d’une tâche, le worker interprète uniquement deux marqueurs JSON stricts : une demande de décision et un appel de compétence. Leur enregistrement appartient à la même transaction que la fin de la tâche ; une panne du sous-système de coordination ne peut toutefois pas empêcher la tâche principale de se terminer. Une décision met en pause la branche de délégation éventuelle et sa réponse est réinjectée dans la même conversation. La boucle de coordination surveille les réparations Self, l’auto-construction des spécialistes et les délégations. Une délégation imbriquée reprend d’abord le fil du spécialiste appelant, puis le résultat final remonte au projet source. La profondeur maximale vaut deux. Un bail SQLite court (agent_coordination_lease) garantit qu’une seule instance traite ces transitions pendant une bascule blue/green ; le bail expire automatiquement si l’instance disparaît.

Les politiques de ressources s’appliquent dans session_worker avant l’acquisition d’un emplacement moteur. Elles ordonnent les tâches en attente, limitent le nombre de moteurs simultanés, suspendent l’admission sous pression CPU/mémoire et réservent les tâches d’arrière-plan à leur fenêtre horaire. Les verrous déjà acquis et les processus en cours ne sont jamais retirés. Le budget de durée alimente un signal persistant et une notification, sans envoyer de signal au processus ni modifier son statut. Les préférences de notifications sont enregistrées par utilisateur et filtrées avant l’ajout à la file Web Push.

Un spécialiste est représenté par un projet global __global_agent__ distinct, un dossier sous data/specialists/ et une discussion de construction. Son projet est créé en SAFE : il écrit seulement dans son atelier et reçoit le chemin source comme référence de lecture. Le résultat revient au projet par une nouvelle tâche de conversation ; l’agent source reste l’unique intégrateur. Désactiver un spécialiste empêche les nouvelles délégations sans supprimer son atelier ni ses fils.

Le canal de l’agent maître ne passe ni par un projet ni par le socket Docker de l’API. Un petit service hôte écoute un socket Unix sous data/host-agent/, authentifie chaque requête avec un jeton 0600 et exécute le CLI sous son identité système dédiée. L’API impose en plus l’authentification administrateur, CSRF et une confirmation par demande privilégiée. Le service n’est pas activé automatiquement par Compose.

La réconciliation de stockage est séparée du runtime applicatif. Son inventaire lit les bases SQLite en mode mode=ro, recoupe les chemins persistés avec les worktrees Git et les verrous, puis calcule les empreintes uniquement lorsqu'un candidat de même catégorie, nom logique et taille existe dans une autre instance. La quarantaine éventuelle utilise un verrou flock, revalide inode, mtime, taille et empreinte contre le plan, puis effectue un renommage atomique vers data/quarantine/<reçu>/payload. Un manifeste 0600, une date d'éligibilité après grâce et un audit JSONL permettent la restauration. Si l'audit échoue, le renommage est annulé avant de rendre l'erreur. Sous le verrou, un second inventaire relit les bases et refuse le déplacement si une référence, une activité ou une exclusion est apparue depuis le dry-run. Une base absente ou illisible, ainsi qu'un schéma sans les tables et colonnes de référence attendues, fait échouer la classification de toute l'instance en mode fermé. Pendant toute la revalidation et le renommage, une transaction BEGIN IMMEDIATE est maintenue sur chaque base dans un ordre stable : aucune nouvelle référence SQLite ne peut être admise entre le contrôle et le mouvement. L'inventaire vérifie chaque composant jusqu'à data/ avec lstat et ne parcourt jamais une instance dont ce parent est symbolique.

Les caches Chromium mutualisables sont isolés du profil (cookies, historique, sessions) sous data/browser-cache/<version majeure>/. Seuls Cache, Code Cache et GPUCache peuvent être rapprochés, et jamais lorsqu'un verrou navigateur est détenu. Les volumes browser-home existants restent privés et hors inventaire implicite.

Le worker spécialisé host_session_worker relie à ce canal les conversations du seul projet global privilégié Pi Doctor/Agent Raspberry Pi. Il conserve les tables conversations, messages et prompt_queue, les verrous de projet et la limite globale d’agents ; seule l’exécution du moteur quitte le conteneur. Le chantier autonome peut ainsi reprendre le même fil après un blocage technique et soumettre le résultat hôte à l’Agent maître. Les autres projets continuent d’utiliser session_worker dans le conteneur.