smol-machines/smolvmEine einbettbare, portable, verzweigbare virtuelle Maschine, um Agents sicher lokal auszuführen.
<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
======
**Verzweigbare microVMs für KI-Agenten.**
Bette leichte virtuelle Maschinen in deine Software ein, portable Entwicklungsumgebungen und lokales Sandboxing.
Installation
------------
```bash
brew install smol-machines/tap/smolvm # macOS (Homebrew)
curl -sSL https://smolmachines.com/install.sh | bash # macOS + Linux
```
Windows: Entpacken Sie die `windows-x86_64`-[Release](https://github.com/smol-machines/smolvm/releases) und führen Sie `smolvm.exe` aus (erfordert die [Windows Hypervisor Platform](https://learn.microsoft.com/en-us/virtualization/api/)). Coding-Agents: Führen Sie nach der Installation `smolvm --help` aus, um alle Befehle zu entdecken.
Die Dokumentation für Menschen und Agents befindet sich in [`docs/`](https://github.com/smol-machines/smolvm/blob/main/docs/README.md), ein Ordner pro Aufgabe: eine `README.md` mit den Fakten und eine `SKILL.md`, der ein Agent folgen kann, mit ihren Skripten, neben der Referenzseite für jede Funktion.
Schnellstart
------------
```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
```
Lokal
------
Echte VMs mit eigenem Kernel, kostenlos auf deinem Laptop oder deinen eigenen Servern. Sie starten in unter einer Sekunde, und der Arbeitsspeicher ist elastisch, sodass der Host nur das bereitstellt, was der Gast tatsächlich nutzt. Maschinen bleiben über Neustarts hinweg erhalten, und jedes OCI-Image funktioniert, auch solche, die du lokal erstellst.
```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
```
Deklariere eine Maschine in einer [Smolfile](https://github.com/smol-machines/smolvm/blob/main/docs/smolfile.md): Image, Ressourcen, Ports, Mounts und Netzwerkrichtlinie in einer eingecheckten Datei.
Einbettbar
----------
Steuere Maschinen aus deinem eigenen Code mit einer einzigen `Machine`-API. Die SDKs laufen in deinem Prozess ohne Daemon, lokal oder auf [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();
```
Quelle und Dokumentation: [smol-machines/smol](https://github.com/smol-machines/smol) · [smolmachines.com/docs/sdk](https://smolmachines.com/docs/sdk)
Verzweigbar
-----------
Speichere eine laufende Maschine mitten in der Ausführung, spule sie zurück oder verzweige sie in Kopien, die vom selben Punkt aus weiterlaufen. Checkpoints erfassen RAM, CPU-Zustand und Festplatten; Branches sind Copy-on-Write-Kinder einer laufenden Maschine.
```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
```
Zurück zu einer früheren Generation mit `--from <checkpoint> --at '~N'` (siehe `machine checkpoint-log`) und ohne Verlust der Ausführung mit [pause and resume](https://github.com/smol-machines/smolvm/blob/main/docs/pause-resume.md) anhalten. Ein auf einem arm64-Mac erstellter Checkpoint wird auf arm64-Linux fortgesetzt, siehe [Moving a running machine from a Mac to Linux](https://github.com/smol-machines/smolvm/blob/main/docs/mac-to-linux.md). Mehr in [Branching](https://github.com/smol-machines/smolvm/blob/main/docs/branching.md) und [incremental checkpoints](https://github.com/smol-machines/smolvm/blob/main/docs/incremental-checkpoints.md).
Portabel
--------
Packen Sie eine Maschine, wie Sie sie auch eingerichtet haben, in eine einzige `.smolmachine`-Datei. Übertragen Sie sie in eine beliebige OCI-Registry oder führen Sie sie als eigenständig ausführbare Datei aus, die in unter 200 ms startet, ohne dass etwas installiert werden muss.
```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
```
Checkpoints sind ebenfalls portabel: Stelle einen auf einem anderen Host oder in der smol-Cloud wieder her.
Sicher
------
Jede Workload erhält eine hardware-isolierte VM mit eigenem Kernel. Netzwerk ist standardmäßig deaktiviert, ausgehender Datenverkehr kann auf benannte Hosts beschränkt werden, und Code kann ein Credential verwenden, ohne es jemals zu lesen.
Sicherheit ist eine gemeinsame Verantwortung. smolvm stellt die Grenze bereit: eine separate VM und ein eigener Kernel für jede Workload, wobei nichts den Host erreicht, sofern du es nicht erlaubst. Du entscheidest, was diese Grenze überschreitet. Jeder Ordner, den du einbindest, jeder Port, den du öffnest, jeder Host, den du erlaubst, und jedes Secret oder jeder SSH-Agent, den du weiterleitest, wird zu etwas, das die Workload nutzen kann – gib einer nicht vertrauenswürdigen Workload daher nur das, was sie benötigt.
```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
```
Siehe [Credential Substitution](https://github.com/smol-machines/smolvm/blob/main/docs/credential-substitution.md) und das [Sicherheitsmodell](https://github.com/smol-machines/smolvm/blob/main/docs/security-model.md).
Verwenden Sie `--allow-host-pattern '*.example.com'`, um nur Subdomains zu erlauben; `--allow-host example.com` erlaubt die Apex-Domain und
ihre Subdomains. `smolvm machine update` fügt Einträge hinzu (`--allow-host`, `--allow-host-pattern`, `--allow-cidr`) und entfernt sie
(`--remove-allow-host`, ein Host oder Muster so, wie es hinzugefügt wurde; `--remove-allow-cidr`), auch auf einer laufenden Maschine,
die mit einer Allow-List gestartet wurde: Eine Freigabe gilt für die nächste Verbindung oder Namensauflösung, und die gelernten Adressen eines entfernten Hosts werden mit ihm entfernt.
Funktionsweise
--------------
Jede Workload läuft in einer hardwarevirtualisierten VM mit eigenem Gast-Kernel auf [Hypervisor.framework](https://developer.apple.com/documentation/hypervisor) (macOS), KVM (Linux) oder der [Windows Hypervisor Platform](https://learn.microsoft.com/en-us/virtualization/api/) (Windows). [libkrun](https://github.com/containers/libkrun) ist der VMM und [libkrunfw](https://github.com/smol-machines/libkrunfw) liefert den Gast-Kernel. Images verwenden das [OCI](https://opencontainers.org/)-Format, sodass alles auf Docker Hub, ghcr.io oder einer anderen Registry als MicroVM startet, ohne Docker-Daemon.
Standardwerte: 4 vCPUs, 8 GiB RAM. Der Speicher ist über virtio-balloon elastisch, und im Leerlauf befindliche vCPUs schlafen im Hypervisor, sodass Überprovisionierung nahezu nichts kostet. Überschreiben Sie dies mit `--cpus` und `--mem`.
Vergleich
---------
| | smolvm | Container | Colima | QEMU | Firecracker | Kata |
|---------------------|--------|------------|--------|------|-------------|------|
| Workload-Grenze | VM + Gast-Kernel | Namespace + gemeinsam genutzter Kernel | Namespace innerhalb einer gemeinsam genutzten VM | VM + Gast-Kernel | VM + Gast-Kernel | VM pro Container |
| Startzeit | <200ms bis Agent bereit | ~100ms | ~Sekunden | ~15-30s | <125ms | ~500ms |
| Architektur | Bibliothek (libkrun) | Daemon | Daemon (in VM) | Prozess | Prozess | Runtime-Stack |
| VMs pro Workload | Ja | Nein | Nein (gemeinsam genutzt) | Ja | Ja | Ja |
| macOS-nativ | Ja | Über Docker-VM | Ja (krunkit) | Ja | Nein | Nein |
| Einbettbares SDK | Ja | Nein | Nein | Nein | Nein | Nein |
| Portable Artefakte | `.smolmachine` | Images (benötigen Daemon) | Nein | Nein | Nein | Nein |
Plattformunterstützung
----------------------
| Host | Gast | Anforderungen |
|------|------|---------------|
| macOS Apple Silicon | arm64 Linux | macOS 11+ |
| macOS Intel | x86_64 Linux | kein Release-Build veröffentlicht; ungetestet |
| Linux x86_64 | x86_64 Linux | KVM (`/dev/kvm`) |
| Linux aarch64 | aarch64 Linux | KVM (`/dev/kvm`) |
| Windows x86_64 | x86_64 Linux | Windows Hypervisor Platform (WHP) aktiviert |
Windows unterstützt portable Checkpoints, Pause/Resume und Branches mit `--freeze-source`. GPU-Beschleunigung bleibt nicht verfügbar; siehe [bekannte Einschränkungen](https://github.com/smol-machines/smolvm/blob/main/docs/limitations.md).
Mehr
----
* [Kubernetes](https://github.com/smol-machines/smolvm/blob/main/docs/kubernetes.md): Pods als MicroVMs über eine `RuntimeClass` ausführen.
* [GPU und CUDA](https://github.com/smol-machines/smolvm/blob/main/docs/gpu.md): Vulkan über virtio-gpu / Venus und CUDA-API-Remoting.
* [Beispiele](https://github.com/smol-machines/smolvm/blob/main/examples): python, node, docker-in-vm, local-llm, headless-browser, doom.
* [Entwicklung](https://github.com/smol-machines/smolvm/blob/main/docs/DEVELOPMENT.md) · Benutzerdokumentation unter [smolmachines.com/docs](https://smolmachines.com/docs/), geschrieben in [smol-machines/docs](https://github.com/smol-machines/docs) (Korrekturen sind dort willkommen; Runtime-Fehler bleiben hier).
smolvm ist die Open-Source-Runtime hinter [smol machines](https://smolmachines.com) und steht in keiner Verbindung zu anderen Projekten namens SmolVM.
[Apache-2.0](https://github.com/smol-machines/smolvm/blob/main/LICENSE) · erstellt von [@binsquare](https://github.com/BinSquare) · [twitter](https://x.com/binsquares) · [github](https://github.com/smol-machines/smolvm)