---
title: "Architecture de Kodema : Kernel, Shell et Userland"
description: "Conception de Kodema : un Kernel pour les exécutions ordonnées, un Shell qui autorise et enregistre, les services Userland, PostgreSQL, NATS et les runtimes."
canonical_url: https://optimi.com/fr/docs/kodema/architecture
md_url: https://optimi.com/fr/docs/kodema/architecture.md
language: fr
alternates:
  - lang: en
    url: https://optimi.com/en/docs/kodema/architecture
    md_url: https://optimi.com/en/docs/kodema/architecture.md
last_updated: 2026-11-14
---

# Architecture

Kodema est un module Go unique organisé en trois couches. **Le Kernel exécute.
Le Shell coordonne et autorise. Le Userland réalise le travail.**

| Couche | Responsabilités |
| --- | --- |
| **Kernel** | Les exécutions, les cycles de vie des actions conteneur et des actions de demande, l’espace de travail partagé, l’annulation, les échéances des actions, la reprise après incident, les journaux et les sorties |
| **Shell** | Le plan de contrôle : tenants, projets, identité, autorisation et vérification, liaisons de ressources, pipelines, tâches, boîte de réception, secrets, comptes de service, persistance, événements, déclenchements sur push, et un routeur d’opérations unique avec une interface REST et une interface MCP |
| **Userland** | Le travail effectif et les intégrations : définitions de pipelines, images, scripts, recettes de livraison, adaptateurs, service Git optionnel, agents |

Les dépendances pointent vers l’intérieur : le Userland dépend des contrats
publics du Shell, et le Shell du Kernel. Le Kernel ne sait rien des tâches, des
rôles, de Git, de HTTP, de SQL, de NATS ni des agents. Les services Userland
utilisent l’API publique et les événements rattachés à un périmètre, jamais les
éléments internes du Shell, et seul le Shell lit la base de données.

**Un plan de contrôle, trois couches**

![kodactl, les clients REST et MCP et les services Userland appellent le Shell à l’intérieur du serveur kodema. Le Shell pilote le Kernel, stocke l’état dans PostgreSQL et publie dans NATS JetStream. Le Kernel démarre, observe et arrête les charges de travail sur Podman ou Kubernetes, et les charges de travail rappellent le Shell avec un jeton d’exécution.](/diagrams/kodema/architecture-fr.svg)

*Le Kernel fait avancer les exécutions ; PostgreSQL enregistre les faits ; NATS distribue l’activité ; le Shell autorise les opérations et les relie.*

## Ce qui s’exécute

| Processus | Rôle |
| --- | --- |
| `kodema server` | Le Shell et le Kernel dans un seul processus : l’API, MCP, les boucles du contrôleur, ainsi que la passerelle de modèles et le proxy MCP optionnels |
| PostgreSQL | L’état, les reçus d’opération, l’audit, la table des événements et les secrets chiffrés |
| NATS JetStream | La distribution des événements et des journaux en direct aux services et aux clients |
| Un runtime de conteneurs | Podman sur un hôte unique, des Jobs Kubernetes en production. Une charge de travail par action conteneur |
| `kodema git serve` (optionnel) | Le compagnon Git : smart HTTP, hooks, règles d’accès, stockage |
| `kodema services` (optionnel) | Les adaptateurs de service : e-mail, webhook, minuterie, répondeur |
| Un fournisseur OIDC | Le vôtre en production. `kodema up` lance le fournisseur intégré, `kodema auth serve` |

Le plan de contrôle s’exécute en une seule réplique. Les projets peuvent
fonctionner sans Git, sans les passerelles et sans agents.

## À qui appartient chaque fait

| Propriétaire | Faits |
| --- | --- |
| PostgreSQL | Tenants, projets, appartenances, pipelines, exécutions, actions, tâches, décisions, reçus, enregistrements de vérification, événements, texte chiffré des secrets |
| NATS | La livraison, pas la vérité. JetStream livre et rejoue les événements au moins une fois ; Core NATS transporte les journaux en direct. La progression des exécutions n’en dépend jamais |
| Le service Git | Les objets Git, les références, les règles d’accès et son journal de réception |
| Votre registre | Les octets des images et des artefacts. Kodema enregistre des références par empreinte |
| Le fournisseur de clés | La clé qui enveloppe la clé de chiffrement de l’installation : un fichier de clés local en test, un KMS cloud en production |

Un changement du domaine valide son état, son enregistrement d’audit et son
événement dans une seule transaction. La table des événements est le flux
durable ; la publication vers NATS est retentée avec les mêmes ID d’événement.
Lorsque NATS est indisponible, la progression des exécutions, les réponses aux
demandes, les déclenchements sur push, le dispatch et les échéances continuent
à partir de PostgreSQL, et un arriéré de publication s’accumule de façon
visible.

## La vie d’une exécution

1. **Admission.** Le Shell authentifie l’appelant, autorise le démarrage,
   valide le YAML, résout les images en empreintes et résout les délais. Une
   seule transaction écrit l’exécution en file d’attente, ses actions, le reçu
   et les événements. L’exécution en file d’attente est l’enregistrement de
   dispatch.
2. **Activation.** Pour une action conteneur, l’échéance est persistée, puis
   une étape de préparation écrit les fichiers en lecture seule sous `/kodema`,
   attache `/workspace`, résout les secrets déclarés et émet le jeton
   d’exécution. Un échec de préparation empêche le démarrage.
3. **Exécution.** Le runtime démarre l’image avec un script qui s’arrête à la
   première erreur, à la place de son point d’entrée. Il fournit le code de
   sortie et les journaux ; le contrôleur est responsable de l’ordonnancement,
   de l’annulation et des échéances.
4. **Clôture.** Un code de sortie zéro fait réussir l’action et promeut ses
   sorties provisoires. Le Kernel active ensuite l’action suivante.
5. **Demande.** Une fois l’arrêt de la charge de travail précédente confirmé,
   le sujet est résolu et persisté, le jeton d’exécution est révoqué, et il
   devient possible de répondre à la demande. Une réponse autorisée la clôt ;
   le Kernel n’interprète jamais les rôles.
6. **Fin et nettoyage.** Le résultat terminal ne change jamais. Le nettoyage de
   la charge de travail et de l’espace de travail est suivi séparément, avec
   ses tentatives et sa dernière erreur.

### Règles de reprise après incident

- Avant un effet qu’il gère, le contrôleur persiste l’intention et une identité
  de ressource stable. Après un plantage, il observe et réconcilie cette charge
  de travail.
- Un lancement n’est retenté automatiquement que s’il existe une preuve que la
  commande ne s’est jamais exécutée. Un résultat inconnu n’est jamais rejoué à
  l’aveugle.
- Transmettre un espace de travail à l’action suivante, activer une demande et
  lancer une exécution de remplacement attendent tous un **arrêt confirmé**. Un
  bail expiré ou un objet Kubernetes supprimé ne suffit pas.
- Un espace de travail perdu fait échouer l’exécution de façon visible. Il
  n’est jamais recréé.

## Identité et identifiants

Les personnes s’authentifient auprès d’un fournisseur OAuth/OIDC externe. Le
Shell valide l’émetteur, la signature, l’audience et l’expiration du jeton
d’accès, puis résout les appartenances courantes à chaque appel.

Les charges de travail et les services utilisent des jetons bearer que le
Shell dérive avec HMAC :

| Jeton | Principal | Durée de vie |
| --- | --- | --- |
| `kodex.<execution-id>.<mac>` | Une exécution en cours | Huit heures au plus, dans la limite de l’échéance de l’action, avec renouvellement sur place pendant une action longue |
| `kodsvc.<service-id>.<mac>` | Un compte de service | Une expiration explicite fixée à l’émission ; la rotation le remplace immédiatement |

Chaque tenant a une clé de dérivation, stockée chiffrée. PostgreSQL ne stocke
ni les jetons ni leurs hachages, seulement un nonce et une expiration par
principal.

- Le jeton d’exécution est effacé lorsqu’une demande commence à attendre, lors
  d’une annulation et à chaque transition terminale. Une charge de travail n’a
  **aucune autorité pendant l’attente d’une demande**.
- La rotation de la clé du tenant invalide d’un coup tous les jetons
  d’exécution et de service de ce tenant.
- Tous les conteneurs d’une exécution partagent son identifiant : l’exécution
  est la frontière de confiance.

## Autorisation et vérification

Chaque opération passe par une seule fonction d’autorisation :

```text
Authorize(principal, operation, resource) → allow | deny
```

C’est du code explicite, pas un langage de politiques. Les opérations
inconnues, les ressources inconnues et les entrées invalides sont refusées.

Les services propriétaires de ressources décident de leurs propres effets, et
demandent des faits au Shell juste avant chacun d’eux :

```text
POST /api/v1/verify
  actor      the credential presented to the service
  resource   a registered resource ID
  operation  the attempted effect and its subject
  approval   optional role/<role> the service’s rules require
→ principal, roles in the resource’s scope, approved, verification ID
```

La vérification authentifie le service appelant, contrôle que sa liaison couvre
la ressource et l’opération, puis vérifie l’acteur séparément. La preuve
d’approbation est une demande antérieure acceptée **dans l’exécution même de
l’acteur**, assignée exactement à ce rôle, et dont le sujet correspond à
l’opération, à la ressource et à chaque champ fourni par le service. La
vérification renvoie des faits, pas des décisions, et chacune est enregistrée.

### Un push protégé, de bout en bout

1. Une exécution pousse vers `refs/heads/main` avec son jeton.
2. Le hook `pre-receive` du service Git appelle `verify` pour chaque mise à
   jour de référence du push, en demandant `approval: role/reviewer` parce que
   les règles indiquent `option approve.refs/heads/main = reviewer`.
3. Le Shell trouve la demande de revue acceptée de cette exécution avec les
   mêmes `ref`, `expected_base` et `candidate`, et répond `approved`.
4. Git applique la mise à jour de façon atomique, uniquement si la référence
   est toujours égale à la base attendue, et la journalise.
5. Le service signale `git.ref.updated` avec l’ID de vérification. Le Shell
   enregistre l’événement ; les pipelines `on.push` y réagissent, sauf pour les
   push effectués par des exécutions.

## Isolation

L’isolation des tenants s’applique aux enregistrements de la base de données,
à l’exécution, au réseau, aux identifiants, aux journaux et aux événements.
PostgreSQL utilise une sécurité au niveau des lignes forcée, sous un rôle
d’exécution qui n’est pas propriétaire des tables. Sur Kubernetes, chaque
tenant a son propre namespace, ses limites de ressources et une politique
réseau qui refuse tout par défaut ; les charges de travail atteignent Kodema,
le service Git configuré et ce que la politique de l’installation autorise.

Le modèle de confiance est celui d’**ingénieurs de projet de confiance
exécutant des conteneurs ordinaires**. Kodema ne prétend pas isoler des charges
de travail hostiles.

## Environnements

L’environnement est sélectionné explicitement, et la production refuse les
adaptateurs de développement et de test :

| Environnement | État et messagerie | Runtime | Clés |
| --- | --- | --- | --- |
| `development` | En mémoire | Processus de l’hôte, pour les tests | Éphémères |
| `test` | PostgreSQL et NATS | Podman ou Kubernetes | Fichier de clés local |
| `production` | PostgreSQL (`sslmode=verify-full`) et NATS (`tls://`) | Jobs Kubernetes | Un KMS cloud : AWS, GCP ou Scaleway |

`kodema up` et le bundle Podman sont des environnements `test` sur une seule
machine.

## Fonctionnalités optionnelles

- **Passerelle de modèles et proxy de modèles en streaming.** Une passerelle
  compatible OpenAI avec des listes de modèles autorisés et l’attribution de
  l’usage, et un proxy pour les protocoles natifs d’Anthropic et d’OpenAI. Les
  identifiants des fournisseurs en amont restent dans le Shell.
- **Proxy MCP.** Des serveurs MCP externes enregistrés et des outils autorisés,
  appelés sous l’autorité courante de l’appelant.
- **Agents.** Les harness externes s’exécutent comme des commandes de
  conteneur. Le runtime natif `kodema agent` ajoute la planification, la revue,
  les opérations Git et des compétences en Markdown. Les deux suivent le même
  cycle de vie de pipeline et n’obtiennent aucune permission particulière.

Les contrats détaillés se trouvent dans le dépôt :
[KODEMA.md](https://github.com/optimiware/kodema/blob/master/KODEMA.md) et les
[spécifications](https://github.com/optimiware/kodema/tree/master/docs/specs).

Suite : **[Exploitation](/fr/docs/kodema/exploitation)**.
