smol-machines/smolvmPortatile, leggera, macchina virtuale autonoma.
Distribuisci ed esegui software con isolamento per impostazione predefinita.
Questo è uno strumento CLI che ti consente di:
.smolmachine) per reidratarla su qualsiasi piattaforma supportata.# installa (macOS + Linux)
curl -sSL https://smolmachines.com/install.sh | bash
# per agenti di codifica — installa + scopri tutti i comandi
curl -sSL https://smolmachines.com/install.sh | bash && smolvm --help
Oppure scarica da GitHub Releases e posizionalo in ~/.local/share/.
Windows: scarica la release windows-x86_64 (include krun.dll + libkrunfw.dll), decomprimila ed esegui smolvm.exe. Richiede la funzionalità Windows Hypervisor Platform (WHP) abilitata.
# esegui un comando in una VM effimera (pulita dopo l'uscita)
smolvm machine run --net --image alpine -- sh -c "echo 'Hello world from a microVM' && uname -a"
# shell interattiva
smolvm machine run --net -it --image alpine -- /bin/sh
# dentro la VM: apk add sl && sl && exit
Uno Smolfile dichiara una macchina in TOML — l'equivalente di un Dockerfile o di un file cloud-init, ma per un'intera VM: immagine, risorse, policy di rete, mount, porte e comandi di configurazione in un unico file versionato.
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 # oppure --smolfile <PATH>
smolvm machine start --name myvm
I mapping delle porte accettano una singola porta ("8080"), un mapping esplicito ("8080:80") o intervalli uno-a-uno di uguale lunghezza ("5173-5180:5173-5180"). Una macchina può pubblicare al massimo 64 mapping concreti.
Le chiavi sconosciute vengono rifiutate anziché ignorate, quindi un errore di battitura fallisce al momento della creazione invece di non fare nulla silenziosamente.
Chiavi comuni: image, cpus, memory, net, ports, volumes, env,
init, workdir, gpu, cuda, docker_socket, storage, overlay e le tabelle [network], [dev], [auth], [health], [restart], [service].
Non hai bisogno di un Dockerfile per mantenere un ambiente. Configura una macchina come preferisci — manualmente o da uno Smolfile — poi impacchetta la macchina arrestata in un artefatto .smolmachine e pubblicalo su qualsiasi registry OCI:
smolvm machine shell --name myvm # installa e configura in modo interattivo
smolvm machine stop --name myvm
smolvm pack create --from-vm myvm -o myvm
smolvm pack push --file myvm.smolmachine ghcr.io/you/myvm:v1
Chiunque può quindi scaricarlo e avviare esattamente la stessa macchina:
smolvm pack pull ghcr.io/you/myvm:v1
Smolfile funzionanti: python · node · docker-in-vm · local-llm · headless-browser · doom
Sandbox per codice non fidato — esegui programmi non fidati in una VM isolata a livello hardware. Il filesystem host, la rete e le credenziali sono separati da un confine ipervisore.
# la rete è disattivata per impostazione predefinita — il codice non fidato non può comunicare con l'esterno
smolvm machine run --image alpine -- nslookup example.com
# fallisce — nessun accesso di rete
# blocca l'egresso — consenti solo host specifici
smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://registry.npmjs.org
# funziona — host consentito
smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://google.com
# fallisce — non nella lista consentita
Impacchetta in eseguibili portabili — trasforma qualsiasi carico di lavoro in un binario autonomo. Tutte le dipendenze sono pre-incluse — nessun passaggio di installazione, nessun download a runtime, avvio in <200ms.
smolvm pack create --image python:3.12-alpine -o ./python312
./python312 run -- python3 --version
# Python 3.12.x — isolato, nessun pyenv/venv/conda necessario
Usa immagini container locali — per CI, host air-gapped e iterazione rapida. Passa a --image un archivio docker save / podman save, convoglialo su stdin, o puntalo a una directory rootfs non compressa. Il lavoro sulle immagini è delegato ai tuoi strumenti container; smolvm avvia semplicemente il risultato.
# compila localmente, esegui nella VM senza push/pull
docker build -t myapp .
docker save myapp | smolvm machine run --image - -- ./app
# da un file di archivio (si avvia senza rete)
smolvm machine run --image ./myapp.tar -- ./app
# da una directory rootfs già decompressa
smolvm machine run --image ./rootfs/ -- ./app
Macchine persistenti per lo sviluppo — crea, arresta, avvia. I pacchetti installati sopravvivono ai riavvii.
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
# dentro: sl, ls, uname -a — digita 'exit' per uscire
smolvm machine stop --name myvm
Usa git e SSH senza copiare chiavi private nell'ospite. Inoltra l'SSH agent del tuo host nella VM. L'ospite può chiedere all'agent di firmare con qualsiasi chiave inoltrata mentre il socket è disponibile, quindi inoltra solo a carichi di lavoro di cui ti fidi. Richiede un SSH agent in esecuzione sul tuo host (ssh-add -l per verificare).
smolvm machine run --ssh-agent --net --image alpine -- sh -c "apk add -q openssh-client && ssh-add -l"
# elenca le tue chiavi host; il materiale della chiave privata rimane nell'agent host
smolvm machine exec --name myvm -- git clone [email protected]:org/private-repo.git
Dichiara ambienti in un file — vedi Smolfile sopra per la configurazione riproducibile della macchina, e per catturare una macchina configurata in un'immagine .smolmachine riutilizzabile senza scrivere un Dockerfile.
Ogni carico di lavoro viene eseguito in una VM virtualizzata a livello hardware con il proprio kernel ospite su Hypervisor.framework (macOS), KVM (Linux) o Windows Hypervisor Platform (Windows). libkrun è il VMM e libkrunfw fornisce il kernel ospite. Impacchettalo in un .smolmachine e funziona ovunque l'architettura host corrisponda, con zero dipendenze.
Le immagini usano il formato OCI — lo stesso standard aperto usato da Docker. Qualsiasi immagine su Docker Hub, ghcr.io o altri registry OCI può essere scaricata e avviata come microVM. Nessun daemon Docker richiesto.
Predefiniti: 4 vCPU, 8 GiB di RAM. La memoria è elastica tramite virtio balloon — l'host impegna solo ciò che l'ospite usa effettivamente e recupera automaticamente il resto. I thread vCPU dormono nell'ipervisore quando inattivi, quindi il sovra-provisioning ha un costo quasi nullo. Sostituisci con --cpus e --mem.
smolvm rafforza il confine ospite/host dando a ogni carico di lavoro una VM e un kernel ospite separati. Non è, di per sé, un piano di controllo multi-utente indurito:
smolvm e VMM vengono eseguiti con i permessi dell'utente host che li invoca. Quel account utente, il sistema operativo host, il backend ipervisore, libkrun e smolvm fanno parte della base di calcolo fidata.--volume sono intenzionalmente esposte all'ospite con l'accesso richiesto. Non montare segreti o percorsi sensibili in un carico di lavoro non fidato.--ssh-agent non copia il materiale della chiave privata nell'ospite, ma concede all'ospite l'accesso al socket dell'agent inoltrato e quindi la capacità di richiedere firme mentre la VM è in esecuzione.--net, l'inoltro delle porte o i servizi host espande la superficie raggiungibile del carico di lavoro.Tratta root nell'ospite come non fidato. Il confine VM limita il suo accesso diretto all'host, mentre ogni capacità inoltrata esplicitamente, inclusi mount, accesso di rete, porte e accesso SSH agent, diventa parte dell'autorità del carico di lavoro.
| smolvm | Containers | Colima | QEMU | Firecracker | Kata | |
|---|---|---|---|---|---|---|
| Confine del carico di lavoro | VM + kernel ospite | Namespace + kernel condiviso | Namespace dentro VM condivisa | VM + kernel ospite | VM + kernel ospite | VM per container |
| Tempo di avvio | <200ms | ~100ms | ~secondi | ~15-30s | <125ms | ~500ms |
| Architettura | Libreria (libkrun) | Daemon | Daemon (in VM) | Processo | Processo | Stack runtime |
| VM per carico di lavoro | Sì | No | No (condivisa) | Sì | Sì | Sì |
| macOS nativo | Sì | Tramite VM Docker | Sì (krunkit) | Sì | No | No |
| SDK incorporabile | Sì | No | No | No | No | No |
| Artefatti portabili | .smolmachine | Immagini (richiedono daemon) | No | No | No | No |
| Host | Ospite | Requisiti |
|---|---|---|
| macOS Apple Silicon | Linux arm64 | macOS 11+ |
| macOS Intel | Linux x86_64 | macOS 11+ (non testato) |
| 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) abilitato |
--net su machine create). Solo TCP/UDP, niente ICMP./workspace (-v /host/dir:/workspace) ha priorità sul workspace predefinito del disco di storage — viene usata la tua directory host.com.apple.security.hypervisor). La release distribuita lo è; un binario ri-firmato o appena compilato lo perde silenziosamente e ogni avvio di VM fallisce con krun_start_enter returned: -22 (EINVAL). Ri-firmalo (ad-hoc va bene): codesign --force --sign - --entitlements hv.entitlements <smolvm-bin> dove hv.entitlements è un plist contenente <key>com.apple.security.hypervisor</key><true/>.--ssh-agent richiede un SSH agent in esecuzione sull'host (SSH_AUTH_SOCK deve essere impostato).GPU=1 e virglrenderer + un driver Vulkan sull'host (vedi Accelerazione GPU sotto).--net funziona come sulle altre piattaforme (virtio-net con inoltro porte in ingresso; TSI per VM solo in uscita), così come machine exec / sessioni interattive e machine stats. Non ancora disponibili su Windows: accelerazione GPU e machine fork / snapshot. Pack create richiede storage-template.ext4 / overlay-template.ext4 accanto a smolvm.exe (Windows non ha mkfs.ext4 host).smolvm espone la GPU host agli ospiti tramite virtio-gpu / Venus (Vulkan-over-virtio). I carichi di lavoro ospite vedono un vero dispositivo Vulkan; su Linux + Intel questo viene renderizzato come:
ANGLE (Intel, Vulkan 1.4 (Virtio-GPU Venus (Intel(R) UHD Graphics ...)), venus)
macOS — virglrenderer e MoltenVK sono inclusi nella distribuzione smolvm. Nessuna installazione aggiuntiva necessaria.
Linux — virglrenderer e un driver Vulkan host devono essere installati dal gestore pacchetti di sistema:
| Distro | Pacchetti |
|---|---|
| Alpine | apk add virglrenderer mesa-vulkan-intel (o mesa-vulkan-ati per AMD) |
| Debian/Ubuntu | apt install virglrenderer0 mesa-vulkan-drivers |
virglrenderer dipende da libEGL e libdrm dello stack del driver GPU host — questi sono specifici dell'hardware e non possono essere inclusi. Qualsiasi host Linux con capacità GPU li avrà già installati tramite il suo driver GPU.
# CLI
smolvm machine run --gpu --image alpine -- vulkaninfo --summary
# Smolfile
# gpu = true
# gpu_vram = 2048 # MiB, predefinito 4096
Il loader Vulkan ospite deve essere puntato all'ICD virtio:
export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/virtio_icd.x86_64.json
Vedi examples/headless-browser/ per una configurazione Chromium funzionante che usa ANGLE + Venus per WebGL accelerato via hardware dentro una VM headless.
--gpu e --cuda forniscono interfacce diverse. --gpu espone Vulkan tramite virtio-gpu / Venus; non fornisce CUDA. --cuda abilita il remoting API CUDA: shim ospite senza driver inoltrano le chiamate CUDA su vsock a un processo host, che le esegue tramite il driver NVIDIA dell'host.
Il remoting CUDA richiede una GPU NVIDIA e un driver NVIDIA funzionante sull'host. Non è passthrough GPU: l'ospite non riceve né il dispositivo fisico né un driver NVIDIA.
Gli host Linux con fork intensivo dovrebbero usare un kernel contenente la correzione KVM a monte
916b7f4.
I kernel interessati possono riportare intermittentemente ENOMEM al primo KVM_RUN anche
con ampia memoria host; smolvm riduce l'esposizione e sostituisce un worker fallito,
ma l'aggiornamento del kernel è la correzione definitiva.
Il confine VM isola comunque CPU, memoria e filesystem del carico di lavoro. L'accesso GPU è mediato da processi host e dalla GPU host condivisa, quindi l'isolamento GPU rimane a livello di processo piuttosto che un confine hardware o VM. Non trattare il remoting CUDA come un confine di isolamento GPU multi-tenant indurito.
Vedi Accesso GPU tramite remoting API: come una microVM senza driver esegue CUDA per il design, i compromessi e il confronto con il passthrough.
Vedi docs/DEVELOPMENT.md.
Apache-2.0 · creato da @binsquare · twitter · github