smol-machines/smolvmUne machine virtuelle intégrable, portable et ramifiable pour exécuter des Agents en toute sécurité en local.
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7141/6b8fd173bd97d64ea831a59cdc2b4fd2392dc9b5f2cc90c91594cdb4925a9949.png" alt="smol machines" width="80">
</p>
<p align="center">
<a href="https://discord.gg/E5r8rEWY9J"><img src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
<a href="https://github.com/smol-machines/smolvm/releases"><img src="https://img.shields.io/github/v/release/smol-machines/smolvm?label=Release" alt="Release"></a>
<a href="https://github.com/smol-machines/smolvm/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License"></a>
<a href="https://www.npmjs.com/package/smolmachines"><img src="https://img.shields.io/npm/v/smolmachines?label=npm&logo=npm" alt="npm"></a>
<a href="https://pypi.org/project/smolmachines/"><img src="https://img.shields.io/pypi/v/smolmachines?label=PyPI&logo=pypi&logoColor=white" alt="PyPI"></a>
<a href="https://crates.io/crates/smolmachines"><img src="https://img.shields.io/crates/v/smolmachines?label=crates.io&logo=rust" alt="crates.io"></a>
</p>
smolvm
======
**MicroVM ramifiables pour agents IA.**
Intégrez des machines virtuelles légères dans vos logiciels, des environnements de développement portables et du bac à sable local.
Installation
------------
```bash
brew install smol-machines/tap/smolvm # macOS (Homebrew)
curl -sSL https://smolmachines.com/install.sh | bash # macOS + Linux
```
Windows : décompressez la [release](https://github.com/smol-machines/smolvm/releases) `windows-x86_64` et exécutez `smolvm.exe` (nécessite la [Windows Hypervisor Platform](https://learn.microsoft.com/en-us/virtualization/api/)). Agents de codage : exécutez `smolvm --help` après l'installation pour découvrir toutes les commandes.
La documentation destinée aux humains et aux agents se trouve dans [`docs/`](https://github.com/smol-machines/smolvm/blob/main/docs/README.md), un dossier par tâche : un `README.md` contenant les faits et un `SKILL.md` qu'un agent peut suivre, avec ses scripts, à côté de la page de référence de chaque fonctionnalité.
Démarrage rapide
----------------
```bash
smolvm machine run --net --image alpine -- uname -a # one-off VM, removed on exit
smolvm machine run --net -it --image alpine -- /bin/sh # interactive shell
```
Local
-----
De vraies VM avec leur propre noyau, gratuites sur votre ordinateur portable ou vos propres serveurs. Elles démarrent en moins d'une seconde, et la mémoire est élastique, de sorte que l'hôte ne réserve que ce que l'invité utilise. Les machines persistent à travers les redémarrages, et n'importe quelle image OCI fonctionne, y compris celles que vous construisez localement.
```bash
smolvm machine create --net --name dev && smolvm machine start --name dev
smolvm machine exec --name dev -- apk add git
docker save myapp | smolvm machine run --image - -- ./app # local image, no registry
```
Déclarez une machine dans un [Smolfile](https://github.com/smol-machines/smolvm/blob/main/docs/smolfile.md) : image, ressources, ports, montages et politique réseau dans un seul fichier versionné.
Intégrable
----------
Pilotez des machines depuis votre propre code avec une seule API `Machine`. Les SDK s'exécutent dans votre processus sans démon, en local ou sur [smol cloud](https://smolmachines.com).
```bash
npm install smolmachines # Node / TypeScript
pip install smolmachines # Python
cargo add smolmachines # Rust
```
```ts
import { Machine } from 'smolmachines';
const m = await Machine.create({ image: 'python:3.12-alpine', network: true });
const r = await m.exec(['python3', '-c', 'print(2 ** 10)']);
console.log(r.stdout); // 1024
await m.delete();
```
Source et docs : [smol-machines/smol](https://github.com/smol-machines/smol) · [smolmachines.com/docs/sdk](https://smolmachines.com/docs/sdk)
Branchable
----------
Sauvegardez une machine en cours d'exécution en pleine exécution, rembobinez-la, ou créez-en des branches sous forme de copies qui continuent de s'exécuter à partir du même point. Les points de contrôle capturent la RAM, l'état du CPU et les disques ; les branches sont des enfants copy-on-write d'une machine active.
```bash
smolvm machine create --net --name agent --image alpine
smolvm machine start --name agent --branchable
smolvm machine branch --from agent --name try-1 # live copy-on-write child
smolvm machine checkpoint --name agent -o agent.checkpoint # save it, processes and all
smolvm machine create --name agent2 --from agent.checkpoint # resume later or elsewhere
```
Revenez à une génération antérieure avec `--from <checkpoint> --at '~N'` (voir `machine checkpoint-log`), et arrêtez-vous sans perdre l'exécution avec [pause and resume](https://github.com/smol-machines/smolvm/blob/main/docs/pause-resume.md). Un checkpoint pris sur un Mac arm64 reprend sur Linux arm64, voir [Moving a running machine from a Mac to Linux](https://github.com/smol-machines/smolvm/blob/main/docs/mac-to-linux.md). Plus dans [Branching](https://github.com/smol-machines/smolvm/blob/main/docs/branching.md) et [incremental checkpoints](https://github.com/smol-machines/smolvm/blob/main/docs/incremental-checkpoints.md).
Portable
--------
Empaquetez une machine, quelle que soit sa configuration, dans un seul fichier `.smolmachine`. Poussez-le vers n'importe quel registre OCI, ou exécutez-le comme un exécutable autonome qui démarre en moins de 200 ms sans rien à installer.
```bash
smolvm machine stop --name dev && smolvm pack create --from-vm dev -o dev
smolvm pack push --file dev.smolmachine ghcr.io/you/dev:v1
smolvm pack create --image python:3.12-alpine -o ./python312
./python312 run -- python3 --version
```
Les points de contrôle sont également portables : restaurez-en un sur un autre hôte ou sur smol cloud.
Sécurité
----
Chaque charge de travail dispose d'une VM isolée au niveau matériel avec son propre noyau. Le réseau est désactivé par défaut, la sortie peut être limitée à des hôtes nommés, et le code peut utiliser un identifiant sans jamais le lire.
La sécurité est une responsabilité partagée. smolvm fournit la frontière : une VM et un noyau distincts pour chaque charge de travail, rien n'atteignant l'hôte sauf si vous l'autorisez. C'est vous qui décidez ce qui franchit cette frontière. Chaque dossier que vous montez, port que vous ouvrez, hôte que vous autorisez, et secret ou agent SSH que vous transmettez devient quelque chose que la charge de travail peut utiliser ; ne donnez donc à une charge de travail non fiable que ce dont elle a besoin.
```bash
smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -qO- https://google.com # blocked
smolvm machine run --net --image alpine --allow-host-pattern registry.npmjs.org -- wget -qO- https://registry.npmjs.org # exact host only
NOTION_API_KEY=secret_… smolvm machine run --net --image alpine \
--credential [email protected] -- sh -c 'echo $NOTION_API_KEY' # a placeholder
```
Voir [substitution des identifiants](https://github.com/smol-machines/smolvm/blob/main/docs/credential-substitution.md) et le [modèle de sécurité](https://github.com/smol-machines/smolvm/blob/main/docs/security-model.md).
Utilisez `--allow-host-pattern '*.example.com'` pour autoriser uniquement les sous-domaines ; `--allow-host example.com` autorise le domaine apex et
ses sous-domaines. `smolvm machine update` ajoute (`--allow-host`, `--allow-host-pattern`, `--allow-cidr`) et supprime
(`--remove-allow-host`, un hôte ou un motif tel qu'il a été ajouté ; `--remove-allow-cidr`) des entrées, y compris sur une machine en cours d'exécution
démarrée avec une liste d'autorisation : une autorisation s'applique à la prochaine connexion ou résolution, et les adresses apprises d'un hôte supprimé disparaissent avec lui.
Comment ça marche
-----------------
Chaque charge de travail s'exécute dans une VM virtualisée par matériel avec son propre noyau invité sur [Hypervisor.framework](https://developer.apple.com/documentation/hypervisor) (macOS), KVM (Linux) ou la [Windows Hypervisor Platform](https://learn.microsoft.com/en-us/virtualization/api/) (Windows). [libkrun](https://github.com/containers/libkrun) est le VMM et [libkrunfw](https://github.com/smol-machines/libkrunfw) fournit le noyau invité. Les images utilisent le format [OCI](https://opencontainers.org/), donc tout ce qui se trouve sur Docker Hub, ghcr.io ou un autre registre démarre comme microVM, sans démon Docker.
Valeurs par défaut : 4 vCPU, 8 Gio de RAM. La mémoire est élastique via virtio balloon et les vCPU inactifs dorment dans l'hyperviseur, donc le surprovisionnement ne coûte presque rien. Remplacez ces valeurs avec `--cpus` et `--mem`.
Comparaison
-----------
| | smolvm | Conteneurs | Colima | QEMU | Firecracker | Kata |
|---------------------|--------|------------|--------|------|-------------|------|
| Frontière de charge de travail | VM + noyau invité | Namespace + noyau partagé | Namespace dans une VM partagée | VM + noyau invité | VM + noyau invité | VM par conteneur |
| Temps de démarrage | <200ms jusqu'à l'agent prêt | ~100ms | ~secondes | ~15-30s | <125ms | ~500ms |
| Architecture | Bibliothèque (libkrun) | Démon | Démon (dans la VM) | Processus | Processus | Pile d'exécution |
| VM par charge de travail | Oui | Non | Non (partagée) | Oui | Oui | Oui |
| Natif macOS | Oui | Via la VM Docker | Oui (krunkit) | Oui | Non | Non |
| SDK intégrable | Oui | Non | Non | Non | Non | Non |
| Artefacts portables | `.smolmachine` | Images (nécessitent un démon) | Non | Non | Non | Non |
Prise en charge des plateformes
-------------------------------
| Hôte | Invité | Prérequis |
|------|-------|-------------|
| macOS Apple Silicon | Linux arm64 | macOS 11+ |
| macOS Intel | Linux x86_64 | aucune version publiée ; non testé |
| Linux x86_64 | Linux x86_64 | KVM (`/dev/kvm`) |
| Linux aarch64 | Linux aarch64 | KVM (`/dev/kvm`) |
| Windows x86_64 | Linux x86_64 | Windows Hypervisor Platform (WHP) activée |
Windows prend en charge les points de contrôle portables, la pause/reprise et les branches avec `--freeze-source`. L'accélération GPU reste indisponible ; voir les [limitations connues](https://github.com/smol-machines/smolvm/blob/main/docs/limitations.md).
Plus
----
* [Kubernetes](https://github.com/smol-machines/smolvm/blob/main/docs/kubernetes.md) : exécuter des pods comme microVM via une `RuntimeClass`.
* [GPU et CUDA](https://github.com/smol-machines/smolvm/blob/main/docs/gpu.md) : Vulkan via virtio-gpu / Venus, et le remoting de l'API CUDA.
* [Exemples](https://github.com/smol-machines/smolvm/blob/main/examples) : python, node, docker-in-vm, local-llm, headless-browser, doom.
* [Développement](https://github.com/smol-machines/smolvm/blob/main/docs/DEVELOPMENT.md) · Documentation utilisateur sur [smolmachines.com/docs](https://smolmachines.com/docs/), rédigée dans [smol-machines/docs](https://github.com/smol-machines/docs) (les corrections y sont les bienvenues ; les bugs d'exécution restent ici).
smolvm est le runtime open source derrière [smol machines](https://smolmachines.com), et n'est pas affilié à d'autres projets nommés SmolVM.
[Apache-2.0](https://github.com/smol-machines/smolvm/blob/main/LICENSE) · réalisé par [@binsquare](https://github.com/BinSquare) · [twitter](https://x.com/binsquares) · [github](https://github.com/smol-machines/smolvm)