smolvm

Distribuez et exécutez des logiciels avec un isolement par défaut.

C'est un outil CLI qui vous permet de :

1. Gérer et exécuter des machines virtuelles Linux personnalisées localement avec : démarrage à froid en moins d'une seconde, multiplateforme (macOS, Linux, Windows), utilisation élastique de la mémoire.
2. Empaqueter une machine virtuelle avec état dans un fichier unique (.smolmachine) pour la réhydrater sur toute plateforme prise en charge.

Installation

# installation (macOS + Linux)
curl -sSL https://smolmachines.com/install.sh | bash

# pour les agents de codage — installer + découvrir toutes les commandes
curl -sSL https://smolmachines.com/install.sh | bash && smolvm --help

Ou téléchargez depuis GitHub Releases, et placez-le dans ~/.local/share/.

Windows : téléchargez la version windows-x86_64 (inclut krun.dll + libkrunfw.dll), décompressez-la, et exécutez smolvm.exe. Nécessite la fonctionnalité Windows Hypervisor Platform (WHP) activée.

Démarrage rapide

# exécuter une commande dans une VM éphémère (nettoyée après la sortie)
smolvm machine run --net --image alpine -- sh -c "echo 'Hello world from a microVM' && uname -a"

# shell interactif
smolvm machine run --net -it --image alpine -- /bin/sh
# dans la VM : apk add sl && sl && exit

Smolfile

Un Smolfile déclare une machine en TOML — l'équivalent d'un Dockerfile ou d'un fichier cloud-init, mais pour une VM entière : image, ressources, politique réseau, montages, ports et commandes de configuration dans un seul fichier versionné.

image = "python:3.12-alpine"
net = true
cpus = 4
memory = 4096

ports = ["8000:8000", "5173-5180:5173-5180"]
volumes = ["./src:/app"]
init = ["pip install -r /app/requirements.txt"]

[network]
allow_hosts = ["api.stripe.com", "pypi.org"]

[auth]
ssh_agent = true

smolvm machine create --name myvm -s Smolfile   # ou --smolfile <PATH>
smolvm machine start --name myvm

Les mappages de ports acceptent un port unique ("8080"), un mappage explicite ("8080:80"), ou des plages un-à-un de longueur égale ("5173-5180:5173-5180"). Une machine peut publier au maximum 64 mappages concrets.

Les clés inconnues sont rejetées plutôt qu'ignorées, donc une faute de frappe échoue au moment de la création au lieu de ne rien faire silencieusement.

Clés courantes : image, cpus, memory, net, ports, volumes, env, init, workdir, gpu, cuda, docker_socket, storage, overlay, et les tables [network], [dev], [auth], [health], [restart], [service].

Instantané d'une machine dans une image réutilisable

Vous n'avez pas besoin d'un Dockerfile pour conserver un environnement. Configurez une machine comme vous le souhaitez — manuellement, ou à partir d'un Smolfile — puis empaquetez la machine arrêtée dans un artefact .smolmachine et poussez-le vers n'importe quel registre OCI :

smolvm machine shell --name myvm          # installer et configurer de manière interactive
smolvm machine stop  --name myvm
smolvm pack create --from-vm myvm -o myvm
smolvm pack push --file myvm.smolmachine ghcr.io/you/myvm:v1

N'importe qui peut ensuite le tirer et démarrer exactement la même machine :

smolvm pack pull ghcr.io/you/myvm:v1

Smolfiles fonctionnels : python · node · docker-in-vm · local-llm · headless-browser · doom

À utiliser pour

Isoler du code non fiable — exécutez des programmes non fiables dans une VM isolée au niveau matériel. Le système de fichiers hôte, le réseau et les identifiants sont séparés par une frontière hyperviseur.

# le réseau est désactivé par défaut — le code non fiable ne peut pas communiquer vers l'extérieur
smolvm machine run --image alpine -- nslookup example.com
# échoue — aucun accès réseau

# verrouiller le trafic sortant — n'autoriser que des hôtes spécifiques
smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://registry.npmjs.org
# fonctionne — hôte autorisé

smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://google.com
# échoue — pas dans la liste d'autorisation

Empaqueter en exécutables portables — transformez n'importe quelle charge de travail en binaire autonome. Toutes les dépendances sont pré-intégrées — aucune étape d'installation, aucun téléchargement à l'exécution, démarrage en <200ms.

smolvm pack create --image python:3.12-alpine -o ./python312
./python312 run -- python3 --version
# Python 3.12.x — isolé, pas besoin de pyenv/venv/conda

Utiliser des images de conteneurs locales — pour le CI, les hôtes isolés du réseau et l'itération rapide. Fournissez à --image une archive docker save / podman save, pipez-en une sur stdin, ou pointez vers un répertoire rootfs décompressé. Le travail sur les images est délégué à vos outils de conteneurs ; smolvm démarre simplement le résultat.

# construire localement, exécuter dans la VM sans push/pull
docker build -t myapp .
docker save myapp | smolvm machine run --image - -- ./app

# à partir d'un fichier d'archive (démarre sans réseau)
smolvm machine run --image ./myapp.tar -- ./app

# à partir d'un répertoire rootfs déjà décompressé
smolvm machine run --image ./rootfs/ -- ./app

Machines persistantes pour le développement — créez, arrêtez, démarrez. Les paquets installés survivent aux redémarrages.

smolvm machine create --net --name myvm
smolvm machine start --name myvm
smolvm machine exec --name myvm -- apk add sl
smolvm machine exec --name myvm -it -- /bin/sh
# à l'intérieur : sl, ls, uname -a — tapez 'exit' pour quitter
smolvm machine stop --name myvm

Utiliser git et SSH sans copier les clés privées dans l'invité. Transférez l'agent SSH de votre hôte dans la VM. L'invité peut demander à l'agent de signer avec n'importe quelle clé transférée tant que le socket est disponible, donc ne le transférez qu'à des charges de travail de confiance. Nécessite un agent SSH en cours d'exécution sur votre hôte (ssh-add -l pour vérifier).

smolvm machine run --ssh-agent --net --image alpine -- sh -c "apk add -q openssh-client && ssh-add -l"
# liste vos clés hôte ; le matériel de clé privée reste dans l'agent hôte

smolvm machine exec --name myvm -- git clone [email protected]:org/private-repo.git

Déclarer des environnements dans un fichier — voir Smolfile ci-dessus pour une configuration de machine reproductible, et pour l'instantané d'une machine configurée dans une image .smolmachine réutilisable sans écrire de Dockerfile.

Comment ça fonctionne

Chaque charge de travail s'exécute dans une VM virtualisée au niveau matériel avec son propre noyau invité sur Hypervisor.framework (macOS), KVM (Linux), ou le Windows Hypervisor Platform (Windows). libkrun est le VMM et libkrunfw fournit le noyau invité. Empaquetez-le dans un .smolmachine et il s'exécute partout où l'architecture hôte correspond, avec zéro dépendance.

Les images utilisent le format OCI — la même norme ouverte qu'utilise Docker. N'importe quelle image sur Docker Hub, ghcr.io, ou d'autres registres OCI peut être tirée et démarrée comme microVM. Aucun démon Docker requis.

Valeurs par défaut : 4 vCPU, 8 Gio de RAM. La mémoire est élastique via virtio balloon — l'hôte ne réserve que ce que l'invité utilise réellement et récupère le reste automatiquement. Les threads vCPU dorment dans l'hyperviseur lorsqu'ils sont inactifs, donc la sur-allocation a un coût quasi nul. Remplacez avec --cpus et --mem.

Modèle de sécurité

smolvm renforce la frontière invité/hôte en donnant à chaque charge de travail une VM et un noyau invité séparés. Ce n'est pas, en soi, un plan de contrôle multi-utilisateurs durci :

• Le CLI smolvm et les processus VMM s'exécutent avec les permissions de l'utilisateur hôte qui les invoque. Ce compte utilisateur, le système d'exploitation hôte, le backend hyperviseur, libkrun et smolvm font partie de la base de confiance informatique.
• Les répertoires hôte passés avec --volume sont intentionnellement exposés à l'invité avec l'accès demandé. Ne montez pas de secrets ou de chemins sensibles dans une charge de travail non fiable.
• --ssh-agent ne copie pas le matériel de clé privée dans l'invité, mais il accorde à l'invité l'accès au socket de l'agent transféré et donc la capacité de demander des signatures pendant que la VM est en cours d'exécution.
• La mise en réseau est désactivée par défaut. L'activation de --net, du transfert de ports ou des services hôte étend la surface accessible de la charge de travail.
• En utilisation locale autonome, l'état et les points de contrôle de smolvm sont limités à l'environnement de l'utilisateur qui les invoque. Pour les co-locataires locaux hostiles, ajoutez une séparation de comptes au niveau hôte et un confinement du système d'exploitation autour du processus VMM. Cette section ne décrit pas le plan de contrôle cloud séparé de smolmachines ni ses garanties d'isolation des locataires.
• Les archives de version publient des sommes de contrôle SHA-256 et l'installateur rejette une non-concordance lorsque le fichier de somme de contrôle est disponible. Les versions ne sont actuellement ni signées ni accompagnées d'attestations de provenance, et l'installateur permet l'installation lorsque le fichier de somme de contrôle ne peut pas être téléchargé.

Traitez root dans l'invité comme non fiable. La frontière VM limite son accès direct à l'hôte, tandis que chaque capacité explicitement transférée, y compris les montages, l'accès réseau, les ports et l'accès à l'agent SSH, fait partie de l'autorité de la charge de travail.

Comparaison

Support de plateforme

Limitations connues

• Le réseau est facultatif (--net sur machine create). TCP/UDP uniquement, pas d'ICMP.
• Montages de volumes : répertoires uniquement (pas de fichiers individuels). Le montage dans /workspace (-v /host/dir:/workspace) a priorité sur l'espace de travail du disque de stockage par défaut — votre répertoire hôte est utilisé à la place.
• macOS : le binaire doit être signé avec les droits Hypervisor.framework (com.apple.security.hypervisor). La version distribuée l'est ; un binaire re-signé ou fraîchement compilé le perd silencieusement et chaque démarrage de VM échoue alors avec krun_start_enter returned: -22 (EINVAL). Re-signez-le (ad-hoc convient) : codesign --force --sign - --entitlements hv.entitlements <smolvm-bin> où hv.entitlements est un plist contenant <key>com.apple.security.hypervisor</key><true/>.
• --ssh-agent nécessite un agent SSH en cours d'exécution sur l'hôte (SSH_AUTH_SOCK doit être défini).
• L'accélération GPU nécessite libkrun compilé avec GPU=1 et virglrenderer + un pilote Vulkan sur l'hôte (voir Accélération GPU ci-dessous).
• Windows : --net fonctionne comme sur les autres plateformes (virtio-net avec transfert de ports entrant ; TSI pour les VM sortantes uniquement), tout comme machine exec / les sessions interactives et machine stats. Pas encore disponible sur Windows : l'accélération GPU et machine fork / l'instantané. La création de pack create nécessite storage-template.ext4 / overlay-template.ext4 à côté de smolvm.exe (Windows n'a pas de mkfs.ext4 hôte).

Accélération GPU

smolvm expose le GPU hôte aux invités via virtio-gpu / Venus (Vulkan-over-virtio). Les charges de travail invitées voient un véritable périphérique Vulkan ; sur Linux + Intel, cela s'affiche comme :

ANGLE (Intel, Vulkan 1.4 (Virtio-GPU Venus (Intel(R) UHD Graphics ...)), venus)

Exigences hôte

macOS — virglrenderer et MoltenVK sont inclus dans la distribution smolvm. Aucune installation supplémentaire nécessaire.

Linux — virglrenderer et un pilote Vulkan hôte doivent être installés depuis le gestionnaire de paquets du système :

virglrenderer dépend de libEGL et libdrm de la pile de pilotes GPU hôte — ceux-ci sont spécifiques au matériel et ne peuvent pas être inclus. Tout hôte Linux compatible GPU les aura déjà installés via son pilote GPU.

Utilisation

# CLI
smolvm machine run --gpu --image alpine -- vulkaninfo --summary

# Smolfile
# gpu = true
# gpu_vram = 2048   # Mio, défaut 4096

Le chargeur Vulkan invité doit être pointé vers l'ICD virtio :

export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/virtio_icd.x86_64.json

Exemple de navigateur sans interface

Voir examples/headless-browser/ pour une configuration Chromium fonctionnelle utilisant ANGLE + Venus pour le WebGL accéléré matériellement dans une VM sans interface.

Relais d'API CUDA

--gpu et --cuda fournissent des interfaces différentes. --gpu expose Vulkan via virtio-gpu / Venus ; il ne fournit pas CUDA. --cuda active le relais d'API CUDA : des shims invités sans pilote transfèrent les appels CUDA via vsock à un processus hôte, qui les exécute via le pilote NVIDIA de l'hôte.

Le relais CUDA nécessite un GPU NVIDIA et un pilote NVIDIA fonctionnel sur l'hôte. Ce n'est pas un passage direct de GPU : l'invité ne reçoit ni le périphérique physique ni un pilote NVIDIA.

Les hôtes Linux fortement forkés doivent utiliser un noyau contenant le correctif KVM en amont 916b7f4. Les noyaux affectés peuvent signaler par intermittence ENOMEM sur le premier KVM_RUN même avec une mémoire hôte abondante ; smolvm réduit l'exposition et remplace un travailleur en échec, mais la mise à jour du noyau est le correctif définitif.

La frontière VM isole toujours le CPU, la mémoire et le système de fichiers de la charge de travail. L'accès GPU est médié par les processus hôte et le GPU hôte partagé, donc l'isolation GPU reste au niveau des processus plutôt qu'une frontière matérielle ou VM. Ne traitez pas le relais CUDA comme une frontière d'isolation GPU multi-locataires durcie.

Voir Accès GPU par relais d'API : comment une microVM sans pilote exécute CUDA pour la conception, les compromis et la comparaison avec le passage direct.

Développement

Voir docs/DEVELOPMENT.md.

Apache-2.0 · créé par @binsquare · twitter · github