Le SDK utilise par défaut le endpoint hébergé. Le même code s'exécute contre votre propre cluster ou un serveur sandbox autonome en définissant `MITOS_BASE_URL`. La clé est résolue à partir de l'argument ou de `MITOS_API_KEY` et n'est jamais journalisée.

### 2. Créer un sandbox et exécuter du code```python
import mitos

sb = mitos.create("python")                  # Ready microVM sandbox (~27 ms warm-claim)
print(sb.exec("echo hello").stdout)          # hello

# Files and a stateful code interpreter hang off the same flat handle.
sb.files.write("/workspace/plan.txt", "draft")
print(sb.run_code("import math; math.sqrt(144)").text)   # 12.0

Le client asynchrone reflète la même surface : `await mitos.aio.create("python")` renvoie un `AsyncDirectSandbox` avec les mêmes `exec` / `run_code` / `files` / `create_pty` / `fork` / `terminate`.

Les `exec` et `run_code` bloquants fonctionnent sur le défaut husk. L'exécution en streaming (`sb.exec(..., on_stdout=...)`), les processus en arrière-plan (`sb.exec_background(...)`) et le PTY interactif (`sb.create_pty()`) passent aujourd'hui par le chemin moteur et sont en cours de portage vers le défaut husk ; `run_code` renvoie un `KernelUnavailable` fail-closed jusqu'à ce que le noyau soit inclus dans l'image de base husk.

### Lancez-le à votre manière

Même moteur, même API, plus de points d'entrée. Pour approfondir, un clic dans [la documentation](https://mitos.run/docs).

**Chaque langage, deux modes.** Chaque SDK parle la même API REST de serveur sandbox en **mode direct** (autonome ou hébergé), et chacun dispose également d'un **mode cluster** (un `AgentRun` qui pilote les CRDs `mitos.run/v1` via l'API Kubernetes). Le nommage du pool par défaut est identique octet pour octet sur les six.

| Langage | Installation | Direct | Cluster | Documentation SDK |
|---|---|---|---|---|
| Python | `pip install mitos-run` | synchrone + asynchrone | `AgentRun` | [sdk/python](https://github.com/mitos-run/mitos/blob/HEAD/sdk/python) |
| TypeScript | `npm i @mitos/sdk` | oui | `AgentRun` | [sdk/typescript](https://github.com/mitos-run/mitos/blob/HEAD/sdk/typescript/README.md) |
| Go | `go get github.com/mitos-run/mitos/sdk/go` | typé, compatible `errors.Is` | `AgentRun` | [sdk/go](https://github.com/mitos-run/mitos/blob/HEAD/sdk/go/README.md) |
| Ruby | gem (stdlib uniquement) | oui | `AgentRun` | [sdk/ruby](https://github.com/mitos-run/mitos/blob/HEAD/sdk/ruby/README.md) |
| Rust | crate (bloquant) | oui | `AgentRun` | [sdk/rust](https://github.com/mitos-run/mitos/blob/HEAD/sdk/rust/README.md) |
| Java | JDK 17 (stdlib uniquement) | oui | `AgentRun` | [sdk/java](https://github.com/mitos-run/mitos/blob/HEAD/sdk/java/README.md) |

Le SDK Go est fourni dans son propre module imbriqué (`github.com/mitos-run/mitos/sdk/go`), de sorte que l'importer n'ajoute jamais le contrôleur à votre build.

**Self-hébergement ? Même code.** Le chart Helm déploie la même passerelle que celle exécutée par le service hébergé, de sorte que le démarrage rapide ci-dessus fonctionne sans modification sur votre propre cluster : pointez `MITOS_BASE_URL` vers votre passerelle et gardez tout le reste inchangé. L'hébergé et l'auto-hébergé ne font qu'une seule expérience ; seuls l'URL et celui qui l'exploite diffèrent.

**Contrôle natif Kubernetes, quand vous le voulez.** Pour les équipes de plateforme qui gèrent les pools de manière déclarative (GitOps, automatisation restreinte par RBAC, opérateurs), le chemin `AgentRun` à deux niveaux contourne la passerelle et pilote directement les CRDs `mitos.run/v1` via l'API Kubernetes :```python
from mitos import AgentRun

c = AgentRun()                                   # kubeconfig or in-cluster; autodetected
sb = c.sandbox("python", ready=True)             # claims a warm sandbox, waits Ready
print(sb.exec("python -c 'print(40 + 2)'").stdout)   # 42

fork_a, fork_b = sb.fork(2)                       # fork against shared warmed state
sb.terminate()

`mitos dev up` démarre un plan de contrôle local en une commande sur un moteur simulé pour
le développement en mode cluster. Un serveur MCP (`mitos-mcp`) expose les sandboxes comme outils MCP
pour tout agent parlant MCP, et une [compétence d'agent](https://github.com/mitos-run/mitos/blob/HEAD/skills/mitos/SKILL.md)
enseigne le workflow aux agents conscients des compétences. La matrice d'installation complète (script,
Homebrew, deb/rpm, scoop/winget, checksums) se trouve dans
[mitos.run/docs/install](https://mitos.run/docs/install).

**Intégrez-vous à l'agent que vous utilisez déjà.** Chaque adaptateur est une fine surcouche des mêmes opérations natives (`exec`, `run_code`, `files`, `fork`), sans dépendance stricte au paquet du framework : Claude Code et opencode (serveur MCP + compétence d'agent), le SDK OpenAI Agents, le SDK Claude Agent, LangChain / deepagents, Vercel AI SDK / Pydantic AI / AutoGen / LlamaIndex (MCP standard), et des shims de migration « changez un seul import » pour les équipes qui quittent les clouds [E2B](https://mitos.run/docs/migrating-from-e2b) ou [Daytona](https://mitos.run/docs/migrating-from-daytona). Le [hub d'intégrations](https://github.com/mitos-run/mitos/blob/HEAD/docs/integrations/README.md) indexe tous les chemins.

**Installez l'opérateur.**```bash
kubectl apply -k deploy/

**Où il s'exécute.** La seule exigence pour un nœud est `/dev/kvm` plus le label `mitos.run/kvm=true`, donc mitos s'installe sur n'importe quel cluster Kubernetes avec des nœuds KVM Bare Metal ou à virtualisation imbriquée :

| plateforme | nœud KVM | guide |
|---|---|---|
| Bare metal (Talos, Hetzner) | `/dev/kvm` natif | [docs/platforms/talos-hetzner.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/platforms/talos-hetzner.md) (référence de première classe) |
| AWS / EKS | groupes de nœuds `*.metal` ou à virtualisation imbriquée | chart générique pour l'instant ; le guide par cloud est l'issue [#919](https://github.com/mitos-run/mitos/issues/919) |
| GKE | pools de nœuds à virtualisation imbriquée | chart générique pour l'instant ; le guide par cloud est [#919](https://github.com/mitos-run/mitos/issues/919) |
| Azure / AKS | tailles de VM compatibles virtualisation imbriquée | chart générique pour l'instant ; le guide par cloud est [#919](https://github.com/mitos-run/mitos/issues/919) |

Le chart et les CRD sont identiques sur toutes ces plateformes ; seul le pool de nœuds qui fournit `/dev/kvm` diffère.

## Pourquoi Mitos

Les harness d'agents ont besoin d'environnements rapides et isolés où les agents lisent et écrivent des fichiers, installent des paquets et exécutent du code non fiable. Chaque option existante impose un compromis : la vitesse sans la propriété, l'isolation sans fork, le natif Kubernetes sans démarrages à chaud, ou une durabilité enfermée dans le cloud de quelqu'un d'autre.

- **Fork en direct d'une VM en cours d'exécution.** Fork copy-on-write à N voies d'une microVM vivante : les filles partagent les pages mémoire du parent jusqu'à ce qu'elles écrivent, donc chaque fork atterrit dans un environnement chaud et prêt. Déclinez un agent en de nombreuses tentatives parallèles.
- **Activation de réclamation à chaud en ~27 ms.** Les microVMs Firecracker se restaurent depuis un instantané mémoire dans la classe des dizaines de millisecondes : P50 ~27 ms sur le nœud de référence bare metal, reproductible via [`bench/husk-activate-latency.sh`](https://github.com/mitos-run/mitos/blob/HEAD/bench/husk-activate-latency.sh).
- **Open source, auto-hébergeable, natif Kubernetes.** À notre connaissance, le seul runtime qui fait les trois. Vous pilotez tout le cycle de vie via des CRD déclaratifs (`mitos.run`).

Deux façons de l'exécuter :

- **Auto-hébergé (aujourd'hui) :** n'importe quel cluster Kubernetes avec des nœuds KVM. Vos données ne quittent jamais votre infrastructure. Le bare metal (Talos + Hetzner) est la plateforme de référence de première classe.
- **Hébergé (en cours) :** le même moteur et la même API opérés par nous, pour les équipes qui veulent des millisecondes sans gérer de nœuds.

> Deux chemins de moteur existent. Le **chemin pod-natif husk est le défaut** : chaque VM s'exécute dans son propre pod non privilégié, et le pod husk source prend un instantané de sa VM en cours d'exécution afin que N pods enfants la restaurent via CoW. Le **chemin raw-forkd** exécute les forks dans le moteur intégré de forkd. Tout ici s'exécute sur le défaut husk, sauf indication explicite `engine path`.

Les sandboxes ne sont pas des pods. Les mécanismes Kubernetes à portée de pod (NetworkPolicy, ResourceQuota, PSA) régissent le pod husk, pas la charge de travail à l'intérieur de la microVM ; le sandbox est la VM, pas le pod husk, et là où nous fournissons un équivalent, il est documenté comme étant le nôtre. Les chemins complets de données `claim` et `exec` ainsi que le diagramme des composants se trouvent sur [mitos.run/docs/architecture](https://mitos.run/docs/architecture).

## Benchmarks

Chaque chiffre ici est reproductible depuis [`bench/`](https://github.com/mitos-run/mitos/blob/HEAD/bench/) sur du vrai matériel KVM ; rien n'est publié qu'un lecteur ne puisse pas régénérer (la règle du projet sur l'absence de revendications non vérifiées). Chaque ligne nomme ce qu'elle mesure et la commande exacte qui la reproduit. Les données complètes par exécution et le contexte matériel se trouvent dans [`bench/results/`](https://github.com/mitos-run/mitos/blob/HEAD/bench/results/).

### Temps jusqu'à l'interactivité hébergé, face à l'ensemble de pairs ComputeSDK

Le temps jusqu'à l'interactivité (TTI) est la seule métrique comparable en toute équité avec le [benchmark ComputeSDK](https://github.com/computesdk/benchmarks) public auquel chaque fournisseur de sandbox hébergé est mesuré : le chronomètre démarre à `create()` et s'arrête lorsqu'une commande a réellement été exécutée dans le sandbox et est revenue.

| fournisseur | TTI P50 | mesure |
|---|---|---|
| northflank | 95.9 ms | publié par ComputeSDK |
| **mitos** | **96.8 ms** | notre harness, `api.mitos.run` |
| daytona | 136.2 ms | publié par ComputeSDK |
| e2b | 365.6 ms | publié par ComputeSDK |

Reproduisez notre chiffre et le tableau des pairs (les chiffres des pairs sont lus depuis le commit immuable publié par ComputeSDK, non ré-exécutés par nous) :```sh
MITOS_API_KEY=... python3 bench/tti-latency.py 100        # our TTI, N=100
python3 bench/peer-tti.py --date 2026-07-09 \
  --ref 3eddee1a972bd49aea56fd6c16d238ca0a45dece            # the peer table

La méthode complète et le matériel sont dans [bench/README.md](https://github.com/mitos-run/mitos/blob/HEAD/bench/README.md) ; les résultats dans [2026-06-19-bare-metal-fork-exec.md](https://github.com/mitos-run/mitos/blob/HEAD/bench/results/2026-06-19-bare-metal-fork-exec.md) et [2026-06-21-kvm-perf-correctness.md](https://github.com/mitos-run/mitos/blob/HEAD/bench/results/2026-06-21-kvm-perf-correctness.md).

### Activation warm-claim (le moteur, pas l'aller-retour)

L'activation warm-sandbox du moteur lui-même (chargement d'instantané + handshake de correction de fork + guest-ready) est P50 ~27 ms sur le nœud de référence bare metal, reproductible à partir de [`bench/husk-activate-latency.sh`](https://github.com/mitos-run/mitos/blob/HEAD/bench/husk-activate-latency.sh). C'est un chiffre plus petit et différent du TTI hébergé de bout en bout ci-dessus ; citer le chiffre du moteur face au chiffre create-API d'un concurrent serait une erreur de catégorie, c'est pourquoi nous les gardons séparés.

## Fonctionnalités

Le chemin pod-natif husk est le défaut. Quelques capacités ne fonctionnent aujourd'hui que sur le `engine path` raw-forkd et sont marquées, avec un lien vers le ticket de suivi.

### Vitesse

| Capacité | Ce que vous obtenez | Docs |
|---|---|---|
| Activation warm-claim | P50 ~27 ms sur le nœud de référence bare metal (chargement d'instantané + handshake de correction de fork + guest-ready) ; ~6-16 ms de restauration d'instantané ; ~3 Mio de mémoire marginale par fork via le partage de pages CoW | [BENCHMARKS.md](https://github.com/mitos-run/mitos/blob/HEAD/BENCHMARKS.md) |
| Pools pré-snapshotés | Images OCI aplaties en rootfs ext4 et préchauffées avec vos étapes `init` avant l'instantané, donc aucun démarrage à froid lors de la revendication | [docs/templates.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/templates.md) |
| Partage de mémoire CoW | Vous payez pour les pages uniques entre forks, pas pour les copies | [mitos.run/docs/metering](https://mitos.run/docs/metering) |
| Distribution à adressage de contenu | Les forks ne récupèrent que les morceaux sha256 manquants auprès d'un détenteur via mTLS ; les reconstructions livrent des deltas sous un contrat de compatibilité de version | [docs/snapshot-distribution.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/snapshot-distribution.md) |

### Isolation

| Capacité | Ce que vous obtenez | Docs |
|---|---|---|
| Isolation matérielle par session | Un noyau dédié par sandbox (KVM/Firecracker) ; sur le défaut husk, chaque VM s'exécute dans son propre pod non privilégié et restreint par PSA, ce qui constitue la frontière par VM | [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model) |
| Aucun héritage silencieux de secrets | Les forks en direct de sandbox contenant des secrets sont rejetés sauf adhésion explicite ; les identifiants sont injectés au moment de la revendication via vsock, jamais intégrés dans les instantanés | [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model) |
| Egress refusé par défaut | Un filtre nftables de refus par défaut dans le netns propre du pod (indépendant du CNI), avec un blocage inconditionnel des métadonnées cloud (169.254.169.254) et une liste d'autorisation par modèle, par IP:port et par nom, via un proxy DNS dans le pod. Vérifié de bout en bout sur un vrai cluster KVM ; l'invité ne peut pas influencer l'application des règles | [mitos.run/docs/networking](https://mitos.run/docs/networking) |
| Chiffrement au repos | Conteneurs LUKS2 par périmètre avec crypto-shredding et enveloppe KMS (derrière `--enable-encryption`, fail-closed) ; les clés adossées à un HSM et le périmètre par espace de travail sont des évolutions ultérieures | [docs/encryption.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/encryption.md) |

### Agent DX

| Capacité | Ce que vous obtenez | Docs |
|---|---|---|
| Exec bloquant | stdout et code de sortie corrects via l'API sandbox | [mitos.run/docs/cli](https://mitos.run/docs/cli) |
| Exec en streaming et PTY | stdout/stderr incrémentaux, processus en arrière-plan et un terminal WebSocket interactif contrôlé par jeton (`engine path`) | [mitos.run/docs/cli](https://mitos.run/docs/cli) |
| Interpréteur de code | `run_code` avec un noyau avec état et des résultats multi-MIME riches, dans chaque SDK et le serveur MCP ; `KernelUnavailable` fail-closed jusqu'à ce que le noyau soit livré dans l'image de base husk | [mitos.run/docs/mcp](https://mitos.run/docs/mcp) |
| Erreurs lisibles par LLM | Chaque échec comporte `{code, cause, remediation}`, analysé par les SDK en une `AgentRunError` structurée | [docs/api/errors.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/api/errors.md) |

### Natif Kubernetes

| Capacité | Ce que vous obtenez | Docs |
|---|---|---|
| CRD déclaratifs | `SandboxPool`, `Sandbox` (source poolRef/fromSandbox/fromRevision), `Workspace`/`WorkspaceRevision` dans `mitos.run/v1` avec topologie de volumes et comportement de fork | [docs/templates.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/templates.md) |
| Exécution pod-native | Chaque VM par sandbox s'exécute dans un pod non privilégié (`/dev/kvm` depuis un plugin de périphériques, pas `privileged`), donc les demandes CPU/mémoire font foi pour l'ordonnanceur et PSA régit le pod | [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model) |
| Ordonnancement conscient de la capacité | Bin-packing CoW sur des détenteurs chauds, un budget de surallocation conscient de CoW, un plafond anti-DoS hôte `MaxSandboxes` avec réservation atomique d'emplacements, et une contre-pression typée `NoCapacity` au lieu de faire un OOM sur un nœud | [docs/scheduling.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/scheduling.md) |
| Autoscaling piloté par la demande | `SandboxPool.spec.autoscale` ajuste le nombre de pods husk dormants à `clamp(inUse + targetSpare, minWarm, maxWarm)` avec un délai de refroidissement anti-thrash ; un pool fixe est simplement `minWarm == replicas` | [docs/scheduling.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/scheduling.md) |
| Sémantique de panne et de GC | TTL de revendication, balayages de VM orphelines, réconciliation au redémarrage du contrôleur, réapération des orphelins de forkd via un journal sur disque, gestion de perte de nœud et contre-pression de saturation, le tout prouvé en CI | [docs/failure-gc.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/failure-gc.md) |

### État durable

| Capacité | Ce que vous obtenez | Docs |
|---|---|---|
| Espaces de travail durables et forkables | CRD `Workspace`/`WorkspaceRevision` : état d'agent durable, versionné et forkable, indépendant de tout sandbox. `/workspace` s'hydrate au démarrage et une révision validée se déshydrate à la terminaison via le stockage à adressage de contenu. Création -> commit -> fork vérifiés sur un vrai cluster KVM | [mitos.run/docs/workspaces](https://mitos.run/docs/workspaces) |
| Sorties et diff | `spec.lifetime.onTerminate.outputs` restreint la déshydratation aux sous-arbres listés ; `{diff: true}` enregistre un diff de hachage de contenu par rapport à la tête parente | [mitos.run/docs/workspaces](https://mitos.run/docs/workspaces) |
| Rendez-vous Git | Une sortie `{git}` pousse des branches par tentative vers un dépôt distant de rendez-vous (le moteur pousse ; un humain ou la CI fusionne). En best-effort sur husk aujourd'hui | [mitos.run/docs/workspaces](https://mitos.run/docs/workspaces) |
| URL d'environnement de développement | `mitos workspace serve <ws> --pool P` revendique à chaud un sandbox forké lié à l'espace de travail et renvoie une URL prête `https://<label>.<expose-domain>/` ; chaque session forkée obtient sa propre URL | [docs/recipes/dev-environment.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/recipes/dev-environment.md) |

### Exploitable

| Capacité | Ce que vous obtenez | Docs |
|---|---|---|
| Métriques et tracing | Métriques Prometheus du nœud et du contrôleur, une trace OpenTelemetry par revendication (`--otlp-endpoint`), et un journal d'audit structuré activable (`--audit-log`) enregistrant commande/chemin et nombre d'octets, jamais le contenu ni les secrets | [mitos.run/docs/observability](https://mitos.run/docs/observability) |
| Comptage conscient de CoW | L'ensemble de pages de modèle partagé est compté une fois, pas une fois par fork, donc la facturation et l'ordonnancement reflètent l'empreinte physique réelle | [mitos.run/docs/metering](https://mitos.run/docs/metering) |
| Outillage pour opérateurs | Le plugin `kubectl mitos` (`ls` / `ps`) et le rapport opérationnel `GET /v1/metering` | [mitos.run/docs/observability](https://mitos.run/docs/observability) |
| Bare metal en première classe | Talos + Hetzner est la plateforme de référence | [docs/platforms/talos-hetzner.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/platforms/talos-hetzner.md) |
| Premier lancement mono-utilisateur | Démarrage rapide k3s avec un portail de connexion à un seul utilisateur (QA uniquement, pas la production) | [docs/platforms/k3s-quickstart.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/platforms/k3s-quickstart.md) |

## Comparaison

Un tableau de chiffres en tête-à-tête n'a sa place ici que lorsque notre harnais pourra le régénérer contre les véritables concurrents sur le même matériel, avec des scripts dans ce dépôt. Ce harnais est le [#15](https://github.com/mitos-run/mitos/issues/15). Les chiffres ci-dessous sont **des chiffres publiés par d'autres fournisseurs, pour des opérations différentes, sur du matériel différent, avec une méthodologie différente** : ils ne sont pas mesurés par nous et ne constituent pas une revendication en tête-à-tête.

| Runtime | Chiffre publié (le leur, pas le nôtre) | Opération qu'ils décrivent |
|---|---|---|
| Mitos (le nôtre, mesuré) | ~27 ms P50 | activation warm-claim sur le nœud de référence bare metal |
| E2B | ~150 ms | création de sandbox |
| Daytona | sub-90 ms | création depuis un instantané |
| Modal | sub-second | création de sandbox |
| CodeSandbox SDK | ~863 ms / ~495 ms | fork en direct / reprise mémoire |
| Fly Machines | < 1 s | démarrage de machine |

Ce qui est comparable et réel aujourd'hui, c'est la carte de Pareto qualitative : la combinaison open source, auto-hébergeable, natif k8s et fork d'instantané en direct est l'axe sur lequel Mitos est seul.

| | Mitos | E2B | Modal | Daytona | Morph | Cloudflare | Box | Agent Sandbox | Kata/KubeVirt | raw Firecracker |
|---|---|---|---|---|---|---|---|---|---|---|
| Isolation matérielle par session | KVM microVM | microVM | gVisor | conteneur/VM | microVM | isolat V8 | VM | option Kata | KVM | KVM |
| Fork d'instantané de l'état en cours d'exécution | oui, primitive centrale | instantané/reprise | instantanés mémoire | non | oui (Infinibranch) | non | fork disque | non | non | DIY |
| Revendications millisecondes sur pools chauds | oui (centre de conception) | pools chauds | pools chauds | espaces de travail | oui | isolats instantanés | non publié | 1-3 s à froid | secondes | DIY |
| Espaces de travail durables et forkables | CRD Workspace | non | volumes | espaces de travail | oui, propriétaire | oui (disque) | non | PVCs | PVCs | non |
| API native Kubernetes | CRDs | API SaaS | API SaaS | SaaS/OSS | API SaaS | API SaaS | CLI native d'agent | CRDs | CRDs | non |
| Auto-hébergeable | oui, tout cluster KVM | OSS partiel | non | noyau OSS | non | non | non | oui | oui | oui |
| Option hébergée | prévue (même moteur) | oui | oui | oui | oui | oui | oui (uniquement) | non | non | non |
| Vos données restent sur votre infra | oui (auto-hébergé) | non | non | partiel | non | non | non | oui | oui | oui |
| Open source | Apache 2.0 | partiel | non | partiel | non | non | non | Apache 2.0 | Apache 2.0 | Apache 2.0 |

Les runtimes SaaS (E2B, Modal, Daytona, Cloudflare) sont rapides, mais le code, les données et les identifiants de vos agents s'exécutent sur l'infrastructure de quelqu'un d'autre, sans chemin d'auto-hébergement à capacité équivalente. Morph a construit le bon modèle d'état (branch/restore) en tant que cloud propriétaire ; notre primitive Workspace vise la même sémantique, en open source, à la vitesse de fork(2). Agent Sandbox (k8s-sigs) est en train de gagner la norme d'API Kubernetes sans moteur de fork d'instantané, c'est pourquoi nous livrons une façade de conformité (`cmd/facade`) pour être son backend le plus rapide plutôt que de la combattre ([docs/facade-conformance.md](https://github.com/mitos-run/mitos/blob/HEAD/docs/facade-conformance.md)). Kata, KubeVirt et Firecracker brut vous donnent la primitive d'isolation et vous laissent les couches pool, fork, distribution et API agent comme problème à résoudre.

Si une alternative nous bat sur un axe qui vous importe et que nous n'avons aucune ligne de feuille de route qui le comble, c'est un bug dans notre stratégie : ouvrez un ticket.

## Architecture

Mitos démarre des microVM Firecracker, les forke via des instantanés copy-on-write, et expose tout le cycle de vie via des CRD déclaratifs (`SandboxPool`, `Sandbox`, `Workspace`) dans le groupe d'API `mitos.run/v1`. Un sandbox est une microVM, pas un pod : il obtient l'isolation matérielle via KVM, et les mécanismes à portée de pod (NetworkPolicy, ResourceQuota, PSA) ne le régissent pas.

Les composants :

- **controller** (Deployment) : réconcilie les CRD, sélectionne un nœud et pilote `forkd`. Il suit les nœuds de fork disponibles via un registre alimenté par des heartbeats de capacité par nœud.
- **forkd** (DaemonSet) : le démon par nœud qui possède les VM. Il expose le gRPC sur `:9090` pour le contrôleur (fork, prepare-pool, heartbeat) et une API HTTP sandbox sur `:9091` pour le trafic exec et fichiers. Il a besoin de `/dev/kvm`, il ne tourne donc que sur les nœuds capables KVM.
- **guest agent** : PID 1 dans chaque microVM. Il parle un protocole vsock pour exec, fichiers, environnement et notifications de fork.
- **sandbox-server** : le même moteur de fork derrière une simple API REST, sans Kubernetes requis, pour les boucles locales et l'utilisation sur un seul hôte.
- **SDK** (`sdk/python`, `sdk/typescript`, `sdk/go`, et plus) : des clients pour le service hébergé, un cluster ou `sandbox-server`.

Deux chemins chauds sont au cœur du système :

- **Chemin de revendication** : le contrôleur choisit un nœud chaud dans le registre et appelle `Fork` de `forkd` via gRPC ; le sandbox résultant signale Ready via l'API HTTP de `forkd` sur ce nœud.
- **Chemin d'exécution** : le SDK ou la CLI parle à `forkd` sur `:9091`, qui fait le pont via vsock vers le guest agent dans la VM.

Le fork est la primitive centrale : une VM source est snapshotée une fois et N enfants restaurent à partir de cet instantané via copy-on-write, de sorte que chaque frère arrive chaud et indépendant tandis que les pages de modèle partagées sont stockées et comptées une seule fois. Parce que Firecracker nécessite la virtualisation matérielle, le bare metal (Talos sur Hetzner est la plateforme de référence) est une cible de première classe ; le plan de contrôle cloud reste sur des nœuds ordinaires tandis que l'exécution atterrit sur des machines capables KVM.

## État du projet

Développement précoce, pré-1.0 (dernière version `v0.3.0`). Ne faites pas encore tourner de code non fiable en production : aucune revue de sécurité externe n'a eu lieu et certains contrôles d'isolation restent ouverts (voir le [modèle de menace](https://mitos.run/docs/threat-model) pour le statut exact par frontière). Le plan de contrôle est réel de bout en bout, prouvé en CI contre des moteurs simulés (mock) et de vraies VM Firecracker, et exercé sur un cluster Talos KVM à nœud unique.

**Vérifié sur un vrai cluster KVM (défaut husk) :** activation warm-claim, exec bloquant, `run_code` qui échoue en fail-closed avec `KernelUnavailable`, auto-réparation / re-pend, préchauffage de pool plus autoscaling piloté par la demande, fork de sandbox en direct (le pod husk source snapshotte sa VM et N pods enfants la restaurent via CoW, chacun étant un enfant Ready indépendant), espaces de travail durables et forkables (create -> commit -> fork), et isolation egress des pods (refus par défaut, blocage des métadonnées cloud, liste d'autorisation par modèle).

**Points restants suivis, pas encore sur le défaut husk :** exec en streaming et PTY interactif ; hooks d'instantané mémoire de VM en direct pour les têtes d'espaces de travail reprenables ; sélection en direct du stockage S3/chiffrement ; le push `{git}` d'espace de travail de husk ; et le multi-nœud N>1 (conçu, vérifié sur nœud unique).

[ROADMAP.md](https://github.com/mitos-run/mitos/blob/HEAD/ROADMAP.md) est la source unique pour ce qui est fait, en cours et bloqué. La règle de fonctionnement : ce dépôt ne décrit jamais un système qui n'existe pas.

## Développement local (KVM non requis)

`mitos dev up` démarre un cluster kind local sur un plan de contrôle simulé (mock) et la CLI `mitos` pilote tout le chemin de revendication ; le moteur mock réconcilie les revendications vers `Ready` et exerce le dispatch du plan de contrôle, mais un vrai `exec` dans une VM nécessite un nœud avec `/dev/kvm`. Pour la boucle REST sans cluster, lancez `go run ./cmd/sandbox-server --mock --addr :8080` et pointez le SDK Python dessus. La procédure pas à pas complète de kind est disponible sur [mitos.run/docs/cli](https://mitos.run/docs/cli).

## Documentation

La documentation complète se trouve sur **[mitos.run/docs](https://mitos.run/docs)** : démarrage rapide, architecture, référence SDK et CLI, cycle de vie des sandbox, espaces de travail, réseau et modèle de menace, le tout rendu à partir de ce dépôt.

La longue traîne complète (modèles, format et distribution des instantanés, chiffrement et secrets, ordonnancement et densité, pannes et GC, correction du moteur de fork, recettes et la spécification cible de l'API v2) se trouve dans [`docs/`](https://github.com/mitos-run/mitos/blob/HEAD/docs/) dans ce dépôt. La méthodologie des benchmarks est dans [BENCHMARKS.md](https://github.com/mitos-run/mitos/blob/HEAD/BENCHMARKS.md).

## Contribuer

Les contributions sont les bienvenues. Voir [CONTRIBUTING.md](https://github.com/mitos-run/mitos/blob/HEAD/CONTRIBUTING.md) et [CLAUDE.md](https://github.com/mitos-run/mitos/blob/HEAD/CLAUDE.md) pour les conventions, et la [page des tickets](https://github.com/mitos-run/mitos/issues) pour le travail suivi par rapport à [ROADMAP.md](https://github.com/mitos-run/mitos/blob/HEAD/ROADMAP.md).

## Sécurité

Le modèle de menace avec le statut par frontière se trouve sur [mitos.run/docs/threat-model](https://mitos.run/docs/threat-model) ; aucune revue de sécurité externe n'a encore eu lieu, et le document indique exactement ce qui est ouvert. Pour signaler une vulnérabilité, voir [SECURITY.md](https://github.com/mitos-run/mitos/blob/HEAD/SECURITY.md).

## Licence

[Apache 2.0](https://github.com/mitos-run/mitos/blob/HEAD/LICENSE).