_    _ _               _      ____          _
   / \  | | |__   ___ _ __| |_   / ___|___   __| | ___
  / _ \ | | '_ \ / _ \ '__| __| | |   / _ \ / _` |/ _ \
 / ___ \| | |_) |  __/ |  | |_  | |__| (_) | (_| |  __/
/_/   \_\_|_.__/ \___|_|   \__|  \____\___/ \__,_|\___|

⚠️ PROJET EXPÉRIMENTAL : Nous testons actuellement plusieurs modèles dans le cadre d'une éventuelle offre pour le code. Le(s) modèle(s) de code d'Albert API peut(vent) changer. ⚠️

Albert Code

Stack d'agentic coding souveraine pour l'État, en une commande : OpenCode + VM isolée + Albert API + skills de l'État + MCP.

Albert Code assemble des briques existantes pour coder avec une IA souveraine, isolée, avec les standards de l'administration embarqués :

• Albert API : modèles souverains de l'État (hébergement SecNumCloud), provider OpenAI-compatible.
• agent-vm (vendored) : sandbox Lima jetable. L'agent tourne en autonomie sans accès à l'hôte.
• OpenCode : le harness (assistant de code en terminal).
• Skills de l'État : DSFR, accessibilité (RGAA), sécurité, data.gouv (à la carte, choisis au setup).
• MCP : data.gouv, context7, playwright, chrome-devtools (à la carte, choisis au setup).

Ce n'est pas un IDE ni un fork : de l'orchestration mince (scripts + config) au-dessus d'OpenCode.

Statut : v1, validé en dogfood bout en bout le 2026-07-02. En test avec des early adopters. Retours et issues bienvenus.

Prérequis

• macOS ou Linux (pas de Windows).
• Lima (installé par le script si absent, via Homebrew).
• Node.js (pour les serveurs MCP lancés via npx).
• Une clé Albert API (réservée aux agents publics : demande sur https://albert.api.etalab.gouv.fr).
• Un compte GitHub (pour que l'agent pousse des PR depuis la VM).

Installation

git clone https://github.com/etalab-ia/albert-code.git ~/albert-code
cd ~/albert-code
./install.sh

Le chemin d'installation ne doit pas contenir d'espace (contrainte du moteur de VM/Lima, qui monte le répertoire de travail dans la VM).

Après installation, tu disposes de la commande albert-code à 3 verbes :

Verbe	Action
albert-code install	1ʳᵉ fois : bootstrap le poste (Lima, VM isolée, clé Albert, skills).
albert-code setup	Par projet, obligatoire avant le 1ᵉʳ run : configure le projet (AGENTS.md + opencode.json + choix skills/MCP).
albert-code run	Lancement : crée la VM de base si absente, puis ouvre la VM isolée.

install.sh est idempotent et non-destructif : il amorce le poste (Phase A) et pose le shim albert-code. Ensuite, c'est albert-code setup puis albert-code run.

Flags : --dry-run (simule sans rien écrire), --help.

Utilisation

albert-code install                                      # 1ʳᵉ fois : bootstrap ton poste
mkdir -p ~/mon-projet && cd ~/mon-projet
albert-code setup                                        # configure le projet (AGENTS.md + MCP + skills)
albert-code run                                          # ouvre la bulle isolée + OpenCode

⚠️ L'ordre compte : install (une fois), puis setup (une fois par projet), puis run. C'est setup qui pose l'opencode.json (provider Albert), les MCP et les skills du projet. Un run sans setup ouvre OpenCode non connecté à Albert (pas de /models, ni MCP, ni skills) : si c'est ton cas, quitte, fais albert-code setup, relance albert-code run.

Dans la bulle, l'agent tourne en mode autonome (--dangerously-skip-permissions), sûr parce que tout est confiné dans la VM. Tu peux lui parler en français.

Les commandes exactes (avec tes valeurs) s'affichent à la fin de albert-code setup, sous « Prochaines étapes ».

Si ton projet a déjà un opencode.json, il est conservé (non-destructif) — vérifie qu'il contient bien le provider Albert, sinon Albert ne sera pas câblé. Voir Dépannage si besoin.

Ressources de la VM

Les défauts du moteur de VM (1 CPU / 3 GiB / 10 GiB) sont trop justes pour un agent de code. Albert Code applique par défaut 4 CPU / 8 GiB / 32 GiB, surchargeables par variable d'environnement :

AC_VM_CPUS=8 AC_VM_MEMORY=16 AC_VM_DISK=64 ./install.sh

Variable	Défaut	Rôle
AC_VM_CPUS	4	CPU alloués (s'applique au lancement de la VM).
AC_VM_MEMORY	8 (GiB)	RAM allouée (s'applique au lancement).
AC_VM_DISK	32 (GiB)	Disque, fixé au 1er lancement, ne peut ensuite que grandir.

Garde-fou hôte (lecture seule, macOS + Linux) : install.sh détecte les ressources de ta machine (sysctl/nproc) et ne propose jamais plus de ~la moitié du CPU/RAM hôte, même si AC_VM_* demande plus — pour ne pas sur-allouer sur un petit poste. Le disque n'est jamais rogné (sparse : alloué à l'usage, pas d'un coup) ; un avertissement s'affiche si l'espace libre est insuffisant.

Push & PR depuis la VM

Par défaut, l'agent peut committer dans la VM mais ni pusher ni ouvrir de PR : la VM isole la bulle de tes credentials hôte (aucun SSH, aucun token). Pour l'autoriser, fournis un token GitHub dédié.

1. Crée un PAT fine-grained sur github.com/settings/personal-access-tokens :
   • Repository access → seulement les dépôts que l'agent doit toucher (pas « All repositories »).
   • Permissions → Contents: Read and write + Pull requests: Read and write (Metadata: read est ajouté d'office).
   • Expiration courte, à renouveler. Token dédié et révocable (pas ton token maître).
2. Pose-le dans ton runtime perso ~/.agent-vm/runtime.sh (hôte, hors de tout dépôt, chmod 600) — jamais dans un opencode.json ni un fichier versionné :

   # --- albert-code : auth GitHub VM ---
   grep -q 'GH_TOKEN'          ~/.zshenv 2>/dev/null || echo "export GH_TOKEN='github_pat_XXXXXXXX'"                 >> ~/.zshenv
   export GH_TOKEN='github_pat_XXXXXXXX'
   grep -q 'AC_GIT_USER_NAME'  ~/.zshenv 2>/dev/null || echo "export AC_GIT_USER_NAME='Prénom Nom'"                  >> ~/.zshenv
   export AC_GIT_USER_NAME='Prénom Nom'
   grep -q 'AC_GIT_USER_EMAIL' ~/.zshenv 2>/dev/null || echo "export AC_GIT_USER_EMAIL='[email protected]'" >> ~/.zshenv
   export AC_GIT_USER_EMAIL='[email protected]'
   # --- /albert-code ---

   Utilise ton email noreply GitHub (settings/emails) pour ne pas exposer ton email perso dans l'historique git.
3. Relance la bulle (albert-code run). Le runtime du bundle branche alors automatiquement le credential helper (gh auth setup-git) et pose l'identité git. git push et gh pr create marchent depuis la VM.

Le token vit dans une bulle exposée au prompt-injection : garde-le fine-grained, scopé, révocable, et relis chaque PR avant merge. Un contenu malveillant pourrait pousser l'agent à en abuser dans la limite de sa portée — d'où les permissions minimales.

Qu'est-ce qu'une skill ? Qu'est-ce qu'un MCP ?

Au setup, Albert Code te propose des skills et des MCP, à la carte : une question Y/n par brique, avec une ligne d'explication. Rien n'est imposé, rien n'est appliqué dans ton dos.

Qu'est-ce qu'une skill ?

Une skill est un mode d'emploi que l'agent charge à la demande : un dossier d'instructions, de conventions et d'exemples pour une tâche précise. Exemples embarqués (Skills de l'État) : appliquer le DSFR, vérifier l'accessibilité RGAA, respecter les règles de sécurité ANSSI, utiliser les API data.gouv.

• Choisie au setup : chaque skill est proposée en Y/n avec son objectif. La sélection est propre au projet (.albert-code/skills.txt).
• Jamais appliquée automatiquement : cocher la skill DSFR ne « DSFR-ise » pas ton projet. Une skill est une capacité en plus, que l'agent mobilise quand tu le lui demandes (« applique le DSFR à cette page ») ou quand la tâche s'y prête clairement. Ton code n'est pas modifié tant que tu ne demandes rien.
• Réversible : relance albert-code setup (ou édite .albert-code/skills.txt) pour changer la sélection.

Qu'est-ce qu'un MCP ?

MCP (Model Context Protocol) est un standard qui branche l'agent sur un outil ou un service externe. Sans MCP, l'agent sait lire/écrire des fichiers et lancer des commandes dans la VM ; chaque MCP lui ajoute un accès structuré à une source ou un outil.

MCP	Ce que l'agent sait faire en plus	Clé
data-gouv	Interroger les données publiques de data.gouv.fr (catalogue, datasets, API tabulaire), en lecture.	aucune
context7	Lire la documentation à jour des librairies et frameworks pendant qu'il code.	gratuite (context7.com/plans), demandée au setup si tu choisis ce MCP
playwright	Piloter un navigateur headless dans la VM : ouvrir une page, cliquer, tester une UI.	aucune
chrome-devtools	Débugger le navigateur : DOM, console, requêtes réseau, performance.	aucune

• Choisis au setup : seuls les MCP que tu acceptes sont écrits dans l'opencode.json du projet.
• La clé Context7 n'est demandée que si tu choisis ce MCP, au moment du setup (jamais à l'install).
• Même un MCP « qui agit » (Playwright) reste confiné à la bulle : c'est l'intérêt de la VM.

Sécurité

• Isolation noyau (Lima) : l'agent n'a aucun accès à tes clés SSH, credentials, cookies ou sessions de l'hôte. La VM est jetable.
• Secrets : les clés (ALBERT_API_KEY, CONTEXT7_API_KEY) ne sont jamais versionnées ni loggées ; elles sont persistées dans le ~/.zshenv de la VM en chmod 600.
• Risque résiduel (prompt-injection) : un contenu malveillant (page web, issue, fichier) pourrait pousser l'agent à exfiltrer une clé par le réseau. Bonnes pratiques : clé Albert dédiée et révocable (pas ta clé maître), revue humaine de chaque PR avant merge, pas de données sensibles confiées à l'agent.

Sous le capot

• Harness : OpenCode uniquement. Provider Albert via @ai-sdk/openai-compatible.

• Modèles Albert embarqués : trois modèles, sélectionnables dans OpenCode via /models.

  Modèle	Rôle	Usage type	Contexte
  Mistral-Medium-3.5-128B	model (défaut)	Usage agentique principal : édition multi-fichiers, refacto, tool calling.	128k
  DeepSeek-V4-Flash	small_model	Tâches légères et rapides (titres, résumés, sous-étapes).	384k
  Qwen/Qwen3.6-27B	disponible (non défaut)	Multimodal (vision) : lire un screenshot, une maquette DSFR, un rendu d'UI. Sélection : albert/Qwen/Qwen3.6-27B.	256k

  Pour changer le modèle par défaut d'un projet, édite model dans son opencode.json.

• Config : opencode.json de portée projet (jamais le global de l'utilisateur, qui peut avoir d'autres providers).

• Skills : etalab-ia/skills cloné dans un cache (~/.config/opencode/.albert-skills-cache) et symliqué dans le dossier scanné par OpenCode. Au setup, chaque skill est proposée en Y/N avec son objectif. La sélection est écrite dans .albert-code/skills.txt à la racine du projet. Au boot de la VM, sync_skills ne symlinke que les skills sélectionnées puis réconcilie (retire les symlinks des skills non sélectionnées, sans jamais toucher les skills perso). Sans manifeste .albert-code/skills.txt, toutes les skills sont installées (rétrocompat). Mise à jour à chaque démarrage de VM.

• MCP : les 4 connecteurs sont désormais tous opt-in. Au setup, chaque MCP est proposé en Y/N avec son objectif : data-gouv (accès aux données publiques), context7 (doc à jour des librairies ; si tu le choisis, la clé gratuite est demandée à ce moment-là : https://context7.com/plans), playwright (navigateur headless), chrome-devtools (debug navigateur). Seuls les MCP acceptés sont écrits dans opencode.json du projet (enabled:false par défaut). Note : le MCP chrome-devtools peut aussi apparaître dans OpenCode même si non coché — il est préinstallé par le moteur d'isolation en amont et n'est pas sous le contrôle d'Albert Code.

• Conventions : AGENTS.md depuis templates/AGENTS.default.md (sécurité, plan mode, task management, code quality, git, accessibilité). Si le projet a déjà son AGENTS.md, il est conservé.

Docs : OpenCode · Albert API · agent-vm · Skills État

Dépannage

• Base VM not found → lance albert-code run une fois ; la VM de base se crée automatiquement.
• Je suis dans OpenCode mais pas connecté à Albert (pas de /models, /mcp, /skills) → tu as lancé albert-code run dans un dossier sans opencode.json (ex. le dépôt albert-code lui-même, ou un projet jamais scaffoldé). Scaffolde d'abord : cd <ton-projet> && albert-code setup, puis relance albert-code run.
• Mon projet a déjà un opencode.json → il est conservé (non-destructif). Vérifie qu'il contient le provider albert ; sinon Albert n'est pas câblé — ajoute à la main le bloc provider.albert + model/small_model.

Désinstallation

./uninstall.sh

Retire le bloc albert-code du runtime VM, le cache et les symlinks skills. Préserve tes skills et ta config perso.

Contribuer

Issues et PR bienvenues. Le dépôt suit ses propres conventions dans AGENTS.md ; le contexte et les décisions sont dans docs/PLAN.md.

Développer Albert Code lui-même : cp config/opencode.template.json opencode.json (déjà gitignoré) puis lance albert-code run — install.sh ne scaffolde pas son propre dépôt.

---

Albert Code · département IA dans l'État (IAE), DINUM · Licence MIT