smol-machines/smolvmВстраиваемая, портативная виртуальная машина с поддержкой ветвления для безопасного локального запуска агентов.
<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 для ИИ-агентов.**
Встраивайте лёгкие виртуальные машины в своё программное обеспечение, портативные среды разработки и локальную изоляцию.
Установка
-------
```bash
brew install smol-machines/tap/smolvm # macOS (Homebrew)
curl -sSL https://smolmachines.com/install.sh | bash # macOS + Linux
```
Windows: распакуйте `windows-x86_64` [release](https://github.com/smol-machines/smolvm/releases) и запустите `smolvm.exe` (требуется [Windows Hypervisor Platform](https://learn.microsoft.com/en-us/virtualization/api/)). Для кодирующих агентов: после установки выполните `smolvm --help`, чтобы узнать все команды.
Документация для людей и агентов находится в [`docs/`](https://github.com/smol-machines/smolvm/blob/main/docs/README.md), по одной папке на задачу: `README.md` с фактами и `SKILL.md`, которому может следовать агент, вместе с его скриптами, рядом со справочной страницей для каждой функции.
Быстрый старт
-----------
```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
```
Локальные
---------
Настоящие виртуальные машины с собственным ядром, бесплатные на вашем ноутбуке или собственных серверах. Они загружаются менее чем за секунду, а память эластична, поэтому хост выделяет только то, что использует гость. Машины сохраняются между перезапусками, и подходит любой OCI-образ, включая те, что вы собрали локально.
```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
```
Объявите машину в [Smolfile](https://github.com/smol-machines/smolvm/blob/main/docs/smolfile.md): образ, ресурсы, порты, монтирования и сетевую политику в одном файле, хранящемся в репозитории.
Встраиваемость
--------------
Управляйте машинами из собственного кода через единый API `Machine`. SDK работают в вашем процессе без демона — локально или в [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();
```
Исходный код и документация: [smol-machines/smol](https://github.com/smol-machines/smol) · [smolmachines.com/docs/sdk](https://smolmachines.com/docs/sdk)
Branchable
----------
Сохраните работающую машину в середине выполнения, откатите её назад или создайте её ветвления в виде копий, которые продолжают работу с той же точки. Контрольные точки фиксируют RAM, состояние CPU и диски; ветвления — это дочерние машины с копированием при записи (copy-on-write) от живой машины.
```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
```
Вернитесь к более раннему поколению с помощью `--from <checkpoint> --at '~N'` (см. `machine checkpoint-log`) и остановитесь без потери выполнения с помощью [паузы и возобновления](https://github.com/smol-machines/smolvm/blob/main/docs/pause-resume.md). Контрольная точка, созданная на arm64 Mac, возобновляется на arm64 Linux, см. [Перенос работающей машины с Mac на Linux](https://github.com/smol-machines/smolvm/blob/main/docs/mac-to-linux.md). Подробнее в разделах [Ветвление](https://github.com/smol-machines/smolvm/blob/main/docs/branching.md) и [инкрементальные контрольные точки](https://github.com/smol-machines/smolvm/blob/main/docs/incremental-checkpoints.md).
Портативность
--------
Упакуйте машину, какой бы вы её ни настроили, в один файл `.smolmachine`. Отправьте его в любой OCI-реестр или запустите как самодостаточный исполняемый файл, который загружается менее чем за 200 мс без необходимости что-либо устанавливать.
```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
```
Контрольные точки также переносимы: восстановите её на другом хосте или в smol cloud.
Безопасность
------------
Каждая рабочая нагрузка получает аппаратно изолированную ВМ с собственным ядром. Сеть по умолчанию отключена, исходящий трафик можно ограничить именованными хостами, а код может использовать учётные данные, никогда их не читая.
Безопасность — это общая ответственность. smolvm обеспечивает границу: отдельная ВМ и ядро для каждой рабочей нагрузки, и ничего не достигает хоста, если вы это не разрешите. Вы решаете, что пересекает эту границу. Каждая монтируемая папка, открываемый порт, разрешаемый хост, а также секрет или SSH-агент, который вы пересылаете, становятся чем-то, что рабочая нагрузка может использовать, поэтому предоставляйте недоверенной рабочей нагрузке только то, что ей необходимо.
```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
```
См. [подстановку учётных данных](https://github.com/smol-machines/smolvm/blob/main/docs/credential-substitution.md) и [модель безопасности](https://github.com/smol-machines/smolvm/blob/main/docs/security-model.md).
Используйте `--allow-host-pattern '*.example.com'`, чтобы разрешить только поддомены; `--allow-host example.com` разрешает apex-домен и
его поддомены. `smolvm machine update` добавляет (`--allow-host`, `--allow-host-pattern`, `--allow-cidr`) и удаляет
(`--remove-allow-host` — хост или шаблон в том виде, в каком он был добавлен; `--remove-allow-cidr`) записи, в том числе на работающей машине,
запущенной со списком разрешений: разрешение применяется к следующему соединению или разрешению имени, а изученные адреса удалённого хоста удаляются вместе с ним.
Как это работает
----------------
Каждая рабочая нагрузка выполняется в аппаратно-виртуализированной ВМ с собственным гостевым ядром на [Hypervisor.framework](https://developer.apple.com/documentation/hypervisor) (macOS), KVM (Linux) или [Windows Hypervisor Platform](https://learn.microsoft.com/en-us/virtualization/api/) (Windows). [libkrun](https://github.com/containers/libkrun) — это VMM, а [libkrunfw](https://github.com/smol-machines/libkrunfw) предоставляет гостевое ядро. Образы используют формат [OCI](https://opencontainers.org/), поэтому всё, что есть на Docker Hub, ghcr.io или в другом реестре, загружается как микро-VM без демона Docker.
По умолчанию: 4 vCPU, 8 ГиБ ОЗУ. Память эластична благодаря virtio balloon, а простаивающие vCPU спят в гипервизоре, поэтому избыточное выделение ресурсов почти ничего не стоит. Переопределяется с помощью `--cpus` и `--mem`.
Сравнение
----------
| | smolvm | Контейнеры | Colima | QEMU | Firecracker | Kata |
|---------------------|--------|------------|--------|------|-------------|------|
| Граница рабочей нагрузки | ВМ + гостевое ядро | Пространство имён + общее ядро | Пространство имён внутри общей ВМ | ВМ + гостевое ядро | ВМ + гостевое ядро | ВМ на контейнер |
| Время загрузки | <200 мс до готовности агента | ~100 мс | ~секунды | ~15–30 с | <125 мс | ~500 мс |
| Архитектура | Библиотека (libkrun) | Демон | Демон (в ВМ) | Процесс | Процесс | Стек среды выполнения |
| Отдельные ВМ на рабочую нагрузку | Да | Нет | Нет (общая) | Да | Да | Да |
| Нативная поддержка macOS | Да | Через ВМ Docker | Да (krunkit) | Да | Нет | Нет |
| Встраиваемый SDK | Да | Нет | Нет | Нет | Нет | Нет |
| Портативные артефакты | `.smolmachine` | Образы (нужен демон) | Нет | Нет | Нет | Нет |
Поддержка платформ
----------------
| Хост | Гость | Требования |
|------|-------|-------------|
| macOS Apple Silicon | arm64 Linux | macOS 11+ |
| macOS Intel | x86_64 Linux | релизная сборка не опубликована; не тестировалось |
| 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) |
Windows поддерживает портативные контрольные точки, паузу/возобновление и ветвления с `--freeze-source`. Ускорение GPU по-прежнему недоступно; см. [известные ограничения](https://github.com/smol-machines/smolvm/blob/main/docs/limitations.md).
Дополнительно
----
* [Kubernetes](https://github.com/smol-machines/smolvm/blob/main/docs/kubernetes.md): запуск подов как микро-VM через `RuntimeClass`.
* [GPU и CUDA](https://github.com/smol-machines/smolvm/blob/main/docs/gpu.md): Vulkan через virtio-gpu / Venus и удалённый доступ к API CUDA.
* [Примеры](https://github.com/smol-machines/smolvm/blob/main/examples): python, node, docker-in-vm, local-llm, headless-browser, doom.
* [Разработка](https://github.com/smol-machines/smolvm/blob/main/docs/DEVELOPMENT.md) · Документация пользователя на [smolmachines.com/docs](https://smolmachines.com/docs/), написанная в [smol-machines/docs](https://github.com/smol-machines/docs) (исправления приветствуются там; ошибки среды выполнения остаются здесь).
smolvm — это среда выполнения с открытым исходным кодом, лежащая в основе [smol machines](https://smolmachines.com), и не связана с другими проектами под названием SmolVM.
[Apache-2.0](https://github.com/smol-machines/smolvm/blob/main/LICENSE) · создано [@binsquare](https://github.com/BinSquare) · [twitter](https://x.com/binsquares) · [github](https://github.com/smol-machines/smolvm)