Aller au contenu

microsandbox

🤖 Rédaction assistée par IA.

En construction

Test en cours de microsandbox comme alternative à Lima, Multipass & co (vu dans etalab-ia/codebox).

microsandbox est un outil (CLI msb et SDK) qui exécute des images OCI (Docker Hub, GHCR...) dans des microVM légères basées sur libkrun, avec un noyau Linux propre à chaque sandbox. Il cible l'exécution de code non fiable, notamment par des agents IA.

Logiciel en bêta

microsandbox est en bêta (« Expect breaking changes, missing features, and rough edges », voir README). Cette fiche est rédigée avec la version 0.7.16.

Points clés

  • Création d'une sandbox en une commande à partir d'une image OCI (msb run debian).
  • Isolation par VM (noyau, système de fichiers et réseau propres) plutôt que par conteneur.
  • Configuration d'une sandbox en YAML (--conf sandbox.yaml : image, ressources, montages, réseau, secrets).
  • Politique réseau fine : liste blanche de domaines, interception TLS, sortie par un proxy HTTP/SOCKS (voir Réseau).
  • Secrets substitués à la volée dans les requêtes vers des domaines autorisés : la sandbox ne voit qu'une valeur de substitution, le secret n'entre jamais dans la VM (voir Secrets).
  • Accès SSH (msb ssh), utile avec VSCode en remote SSH.
  • Snapshots et forks de sandbox (msb snapshot, msb fork).
  • SDK TypeScript, Python, Rust, Go et Ruby pour piloter les sandboxes depuis du code.

Systèmes supportés

Voir docs.microsandbox.dev - CLI :

OS Pré-requis
Linux (x64, ARM64) glibc 2.28+ et KVM (/dev/kvm), voir Troubleshooting Linux
macOS Apple Silicon uniquement (pas de Mac Intel), voir Troubleshooting macOS
Windows 10/11 (x64, ARM64), preview Fonctionnalité Windows Hypervisor Platform (HypervisorPlatform), voir Troubleshooting Windows

Sous Windows, HypervisorPlatform est distincte de Plateforme de machine virtuelle (VirtualMachinePlatform) activée pour WSL2 :

Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All -NoRestart

Installation

Voir docs.microsandbox.dev - CLI :

# Linux et macOS (installation dans ~/.microsandbox avec un lien dans ~/.local/bin)
curl -fsSL https://install.microsandbox.dev | sh
# Windows (preview)
irm https://install.microsandbox.dev/windows | iex

Vérification :

msb --version
# vérification de la configuration de l'hôte (KVM, WHP...)
msb doctor

Mise à jour : msb update.

Principales commandes

Les liens pointent vers la référence de la ligne de commande :

Action Commande
Afficher l'aide msb --help
Exécuter une commande dans une sandbox msb run debian -- <commande> (sandbox supprimée à la sortie)
Créer et démarrer une sandbox en tâche de fond msb create --name <nom> --cpus 4 --memory 4G [--conf sandbox.yaml] [image]
Lister les sandboxes msb list
Afficher le détail d'une sandbox msb inspect <nom>
Ouvrir un shell dans la sandbox msb ssh <nom>
Exécuter une commande dans la sandbox msb exec <nom> -- <commande>
Monter un dossier ou un volume -v ./src:/app (dossier de l'hôte) ou --mount-named <volume>:/data (volume nommé) à la création
Copier un fichier vers la sandbox msb copy fichier.txt <nom>:/chemin/absolu
Arrêter / démarrer la sandbox msb stop <nom> / msb start <nom>
Supprimer la sandbox msb remove <nom> (msb rm -f <nom> si elle tourne)

Configuration

Fichier de configuration

Il est possible de passer un fichier YAML qui décrit la sandbox avec --conf (voir docs.microsandbox.dev - Configuration) :

image: "ubuntu:24.04"
cpus: 4
memory: "4G"
workdir: "/workspace"
mounts:
  - named: workspace
    target: "/workspace"
    create: ensure-exists
network:
  allow: ["github.com", "api.github.com"]
  tls:
    enabled: true
msb create --name devbox --conf sandbox.yaml
msb ssh devbox

Réseau

Voir docs.microsandbox.dev - Networking :

  • Par défaut, l'accès à Internet est autorisé, mais les adresses privées, loopback, link-local et le service de métadonnées cloud sont bloqués.
  • Une liste network.allow non vide bloque tout le reste (y compris la résolution DNS des domaines non autorisés).
  • Le mode strict (actif par défaut) impose l'interception TLS (network.tls.enabled: true ou --tls-intercept) pour autoriser du HTTPS sur un nom de domaine : msb vérifie alors l'en-tête Host réellement demandé.

Secrets

Les secrets sont déclarés avec une liste de domaines de destination (voir docs.microsandbox.dev - Secrets). La sandbox ne voit qu'une valeur factice, remplacée par la vraie valeur par msb uniquement dans les requêtes vers ces domaines :

secrets:
  GITHUB_TOKEN:
    allow: ["api.github.com", "github.com"]
secret_violation_action: block-and-log

Proxy sortant

L'option --proxy fait sortir le trafic de la sandbox par un proxy.

⚠️ Le filtrage par domaine est fait par msb : le proxy reçoit actuellement CONNECT <IP>:<port> et ne voit pas le nom de domaine1.

Voir :

Limites

Pas de GPU

Aucun support GPU n'est documenté : pas de PyTorch CUDA dans une sandbox.

KVM dans la sandbox

La virtualisation imbriquée s'active avec --nested-virt (désactivée par défaut).

Sur un hôte déjà virtualisé (VDI, VM cloud, runner CI, WSL2), microsandbox ne démarre que si l'hyperviseur sous-jacent expose la virtualisation imbriquée (/dev/kvm).

Pour vérifier dans la sandbox, voir le diagnostic de la fiche KVM - Pré-requis.

Images OCI et non VM complètes

Une sandbox démarre à partir d'une image de conteneur et non d'une image cloud : pas de cloud-init comme avec Multipass ou Lima. Le provisionnement se fait plutôt dans l'image (Dockerfile).

Ressources


  1. Voir superradcompany/microsandbox#1773 - How should DNS resolution work with outbound proxies? (issue ouverte au 20/11/2026) sur l'envoi du nom d'hôte dans le CONNECT. ↩