smol-machines/smolvmUna macchina virtuale incorporabile, portatile e ramificabile per eseguire in sicurezza gli Agenti in locale.
<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 diramabili per agenti AI.**
Integra macchine virtuali leggere nel tuo software, ambienti di sviluppo portatili e sandboxing locale.
Installa
--------
```bash
brew install smol-machines/tap/smolvm # macOS (Homebrew)
curl -sSL https://smolmachines.com/install.sh | bash # macOS + Linux
```
Windows: decomprimere la release `windows-x86_64` [release](https://github.com/smol-machines/smolvm/releases) ed eseguire `smolvm.exe` (richiede la [Windows Hypervisor Platform](https://learn.microsoft.com/en-us/virtualization/api/)). Agenti di coding: eseguire `smolvm --help` dopo l'installazione per scoprire tutti i comandi.
La documentazione per umani e agenti si trova in [`docs/`](https://github.com/smol-machines/smolvm/blob/main/docs/README.md), una cartella per attività: un `README.md` con i fatti e un `SKILL.md` che un agente può seguire, con i relativi script, accanto alla pagina di riferimento per ciascuna funzionalità.
Avvio rapido
------------
```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
```
Locale
-------
VM reali con il proprio kernel, gratuiti sul tuo laptop o sui tuoi server. Si avviano in meno di un secondo e la memoria è elastica, quindi l'host impegna solo ciò che il guest utilizza. Le macchine persistono tra i riavvii e qualsiasi immagine OCI funziona, comprese quelle che costruisci localmente.
```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
```
Dichiara una macchina in un [Smolfile](https://github.com/smol-machines/smolvm/blob/main/docs/smolfile.md): immagine, risorse, porte, mount e policy di rete in un unico file versionato.
Integrabile
----------
Gestisci le macchine dal tuo codice con un'unica API `Machine`. Gli SDK vengono eseguiti nel tuo processo senza daemon, in locale o su [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();
```
Origine e documentazione: [smol-machines/smol](https://github.com/smol-machines/smol) · [smolmachines.com/docs/sdk](https://smolmachines.com/docs/sdk)
Branchable
----------
Salva una macchina in esecuzione a metà dell'esecuzione, riavvolgila o crea dei rami in copie che continuano a funzionare dallo stesso punto. I checkpoint catturano RAM, stato della CPU e dischi; i rami sono figli copy-on-write di una macchina attiva.
```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
```
Torna a una generazione precedente con `--from <checkpoint> --at '~N'` (vedi `machine checkpoint-log`), e fermati senza perdere l'esecuzione con [pause and resume](https://github.com/smol-machines/smolvm/blob/main/docs/pause-resume.md). Un checkpoint creato su un Mac arm64 riprende su Linux arm64, vedi [Moving a running machine from a Mac to Linux](https://github.com/smol-machines/smolvm/blob/main/docs/mac-to-linux.md). Maggiori dettagli in [Branching](https://github.com/smol-machines/smolvm/blob/main/docs/branching.md) e [incremental checkpoints](https://github.com/smol-machines/smolvm/blob/main/docs/incremental-checkpoints.md).
Portable
--------
Impacchetta una macchina, indipendentemente da come l'hai configurata, in un singolo file `.smolmachine`. Caricalo su qualsiasi registry OCI, oppure eseguilo come eseguibile autonomo che si avvia in meno di 200 ms senza nulla da installare.
```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
```
I checkpoint sono portabili: ripristinane uno su un altro host o su smol cloud.
Sicuro
------
Ogni workload ottiene una VM isolata a livello hardware con il proprio kernel. Il networking è disattivato per impostazione predefinita, l'egress può essere limitato a host specifici e il codice può utilizzare una credenziale senza mai leggerla.
La sicurezza è una responsabilità condivisa. smolvm fornisce il confine: una VM e un kernel separati per ogni workload, senza che nulla raggiunga l'host a meno che tu non lo consenta. Sei tu a decidere cosa attraversa quel confine. Ogni cartella che monti, porta che apri, host che consenti e secret o SSH agent che inoltri diventa qualcosa che il workload può utilizzare, quindi assegna a un workload non attendibile solo ciò di cui ha bisogno.
```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
```
Vedi [sostituzione delle credenziali](https://github.com/smol-machines/smolvm/blob/main/docs/credential-substitution.md) e il [modello di sicurezza](https://github.com/smol-machines/smolvm/blob/main/docs/security-model.md).
Usa `--allow-host-pattern '*.example.com'` per consentire solo i sottodomini; `--allow-host example.com` consente l'apex e
i suoi sottodomini. `smolvm machine update` aggiunge (`--allow-host`, `--allow-host-pattern`, `--allow-cidr`) e rimuove
(`--remove-allow-host`, un host o pattern così come è stato aggiunto; `--remove-allow-cidr`) voci, anche su una macchina in esecuzione
avviata con una allow list: un'autorizzazione si applica alla connessione o alla risoluzione successiva, e gli indirizzi appresi di un host rimosso vengono rimossi con esso.
Come funziona
-------------
Ogni workload viene eseguito in una VM con virtualizzazione hardware e un proprio kernel guest su [Hypervisor.framework](https://developer.apple.com/documentation/hypervisor) (macOS), KVM (Linux) o [Windows Hypervisor Platform](https://learn.microsoft.com/en-us/virtualization/api/) (Windows). [libkrun](https://github.com/containers/libkrun) è il VMM e [libkrunfw](https://github.com/smol-machines/libkrunfw) fornisce il kernel guest. Le immagini usano il formato [OCI](https://opencontainers.org/), quindi qualsiasi cosa su Docker Hub, ghcr.io o un altro registry si avvia come microVM, senza alcun daemon Docker.
Valori predefiniti: 4 vCPU, 8 GiB di RAM. La memoria è elastica tramite virtio balloon e le vCPU inattive dormono nell'hypervisor, quindi il sovradimensionamento non costa quasi nulla. Sovrascrivi con `--cpus` e `--mem`.
Confronto
----------
| | smolvm | Container | Colima | QEMU | Firecracker | Kata |
|---------------------|--------|------------|--------|------|-------------|------|
| Confine del workload | VM + kernel guest | Namespace + kernel condiviso | Namespace all'interno di una VM condivisa | VM + kernel guest | VM + kernel guest | VM per container |
| Tempo di avvio | <200ms fino all'agente pronto | ~100ms | ~secondi | ~15-30s | <125ms | ~500ms |
| Architettura | Libreria (libkrun) | Daemon | Daemon (nella VM) | Processo | Processo | Stack di runtime |
| VM per workload | Sì | No | No (condivisa) | Sì | Sì | Sì |
| Nativo su macOS | Sì | Tramite VM Docker | Sì (krunkit) | Sì | No | No |
| SDK integrabile | Sì | No | No | No | No | No |
| Artefatti portabili | `.smolmachine` | Immagini (richiedono un daemon) | No | No | No | No |
Supporto alle piattaforme
-------------------------
| Host | Guest | Requisiti |
|------|-------|-------------|
| macOS Apple Silicon | Linux arm64 | macOS 11+ |
| macOS Intel | Linux x86_64 | nessuna build di rilascio pubblicata; 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 |
Windows supporta checkpoint portabili, pausa/ripresa e branch con `--freeze-source`. L'accelerazione GPU rimane non disponibile; vedi [limitazioni note](https://github.com/smol-machines/smolvm/blob/main/docs/limitations.md).
Altro
-----
* [Kubernetes](https://github.com/smol-machines/smolvm/blob/main/docs/kubernetes.md): esegui i pod come microVM tramite una `RuntimeClass`.
* [GPU e CUDA](https://github.com/smol-machines/smolvm/blob/main/docs/gpu.md): Vulkan tramite virtio-gpu / Venus e remoting dell'API CUDA.
* [Esempi](https://github.com/smol-machines/smolvm/blob/main/examples): python, node, docker-in-vm, local-llm, headless-browser, doom.
* [Sviluppo](https://github.com/smol-machines/smolvm/blob/main/docs/DEVELOPMENT.md) · Documentazione utente su [smolmachines.com/docs](https://smolmachines.com/docs/), scritta in [smol-machines/docs](https://github.com/smol-machines/docs) (correzioni benvenute lì; i bug del runtime restano qui).
smolvm è il runtime open-source dietro [smol machines](https://smolmachines.com) e non è affiliato ad altri progetti chiamati SmolVM.
[Apache-2.0](https://github.com/smol-machines/smolvm/blob/main/LICENSE) · realizzato da [@binsquare](https://github.com/BinSquare) · [twitter](https://x.com/binsquares) · [github](https://github.com/smol-machines/smolvm)