smolvm

Distribuye y ejecuta software con aislamiento por defecto.

Esta es una herramienta CLI que te permite:

1. Gestionar y ejecutar máquinas virtuales Linux personalizadas localmente con: arranque en frío en menos de un segundo, multiplataforma (macOS, Linux, Windows) y uso elástico de memoria.
2. Empaquetar una máquina virtual con estado en un único archivo (.smolmachine) para rehidratarla en cualquier plataforma compatible.

Instalación

# instalar (macOS + Linux)
curl -sSL https://smolmachines.com/install.sh | bash

# para agentes de codificación — instalar + descubrir todos los comandos
curl -sSL https://smolmachines.com/install.sh | bash && smolvm --help

O descárgalo desde GitHub Releases y colócalo en ~/.local/share/.

Windows: descarga la versión windows-x86_64 (incluye krun.dll + libkrunfw.dll), descomprímela y ejecuta smolvm.exe. Requiere la función Windows Hypervisor Platform (WHP) habilitada.

Inicio Rápido

# ejecutar un comando en una VM efímera (se limpia al salir)
smolvm machine run --net --image alpine -- sh -c "echo 'Hello world from a microVM' && uname -a"

# shell interactivo
smolvm machine run --net -it --image alpine -- /bin/sh
# dentro de la VM: apk add sl && sl && exit

Smolfile

Un Smolfile declara una máquina en TOML — el equivalente a un Dockerfile o un archivo cloud-init, pero para una VM completa: imagen, recursos, política de red, montajes, puertos y comandos de configuración en un único archivo versionado.

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   # o --smolfile <PATH>
smolvm machine start --name myvm

Los mapeos de puertos aceptan un puerto único ("8080"), un mapeo explícito ("8080:80") o rangos uno a uno de igual longitud ("5173-5180:5173-5180"). Una máquina puede publicar como máximo 64 mapeos concretos.

Las claves desconocidas se rechazan en lugar de ignorarse, por lo que un error tipográfico falla en el momento de la creación en lugar de no hacer nada silenciosamente.

Claves comunes: image, cpus, memory, net, ports, volumes, env, init, workdir, gpu, cuda, docker_socket, storage, overlay y las tablas [network], [dev], [auth], [health], [restart], [service].

Crear una instantánea de una máquina en una imagen reutilizable

No necesitas un Dockerfile para mantener un entorno. Configura una máquina como prefieras — manualmente o desde un Smolfile — luego empaqueta la máquina detenida en un artefacto .smolmachine y súbelo a cualquier registro OCI:

smolvm machine shell --name myvm          # instalar y configurar interactivamente
smolvm machine stop  --name myvm
smolvm pack create --from-vm myvm -o myvm
smolvm pack push --file myvm.smolmachine ghcr.io/you/myvm:v1

Cualquiera puede luego descargarlo e iniciar exactamente la misma máquina:

smolvm pack pull ghcr.io/you/myvm:v1

Smolfiles funcionales: python · node · docker-in-vm · local-llm · headless-browser · doom

Usa Esto Para

Aislar código no confiable — ejecuta programas no confiables en una VM aislada por hardware. El sistema de archivos del host, la red y las credenciales están separados por un límite de hipervisor.

# la red está desactivada por defecto — el código no confiable no puede comunicarse con el exterior
smolvm machine run --image alpine -- nslookup example.com
# falla — sin acceso a la red

# restringe la salida — solo permite hosts específicos
smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://registry.npmjs.org
# funciona — host permitido

smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://google.com
# falla — no está en la lista de permitidos

Empaquetar en ejecutables portátiles — convierte cualquier carga de trabajo en un binario autocontenido. Todas las dependencias están preintegradas — sin paso de instalación, sin descargas en tiempo de ejecución, arranca en <200ms.

smolvm pack create --image python:3.12-alpine -o ./python312
./python312 run -- python3 --version
# Python 3.12.x — aislado, sin necesidad de pyenv/venv/conda

Usar imágenes de contenedores locales — para CI, hosts aislados y iteración rápida. Pasa a --image un archivo de docker save / podman save, envíalo por stdin, o apúntalo a un directorio rootfs desempaquetado. El trabajo de imágenes se delega a tus herramientas de contenedores; smolvm solo inicia el resultado.

# compilar localmente, ejecutar en la VM sin push/pull
docker build -t myapp .
docker save myapp | smolvm machine run --image - -- ./app

# desde un archivo (arranca sin red)
smolvm machine run --image ./myapp.tar -- ./app

# desde un directorio rootfs ya desempaquetado
smolvm machine run --image ./rootfs/ -- ./app

Máquinas persistentes para desarrollo — crea, detén, inicia. Los paquetes instalados sobreviven a los reinicios.

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 — escribe 'exit' para salir
smolvm machine stop --name myvm

Usa git y SSH sin copiar claves privadas al invitado. Reenvía el agente SSH de tu host a la VM. El invitado puede pedir al agente que firme con cualquier clave reenviada mientras el socket esté disponible, así que reenvíalo solo a cargas de trabajo de confianza. Requiere un agente SSH ejecutándose en tu host (ssh-add -l para comprobarlo).

smolvm machine run --ssh-agent --net --image alpine -- sh -c "apk add -q openssh-client && ssh-add -l"
# lista tus claves del host; el material de la clave privada permanece en el agente del host

smolvm machine exec --name myvm -- git clone [email protected]:org/private-repo.git

Declarar entornos en un archivo — consulta Smolfile arriba para configuración reproducible de máquinas, y para crear una instantánea de una máquina configurada en una imagen .smolmachine reutilizable sin escribir un Dockerfile.

Cómo Funciona

Cada carga de trabajo se ejecuta en una VM virtualizada por hardware con su propio kernel invitado en Hypervisor.framework (macOS), KVM (Linux) o Windows Hypervisor Platform (Windows). libkrun es el VMM y libkrunfw proporciona el kernel invitado. Empaquétalo en un .smolmachine y se ejecutará en cualquier lugar donde coincida la arquitectura del host, con cero dependencias.

Las imágenes usan el formato OCI — el mismo estándar abierto que usa Docker. Cualquier imagen en Docker Hub, ghcr.io u otros registros OCI se puede descargar e iniciar como microVM. No se requiere demonio Docker.

Valores por defecto: 4 vCPUs, 8 GiB de RAM. La memoria es elástica mediante virtio balloon — el host solo compromete lo que el invitado realmente usa y reclama el resto automáticamente. Los hilos de vCPU duermen en el hipervisor cuando están inactivos, por lo que el sobreaprovisionamiento tiene un costo casi nulo. Anula con --cpus y --mem.

Modelo de Seguridad

smolvm refuerza el límite invitado/host al dar a cada carga de trabajo una VM y un kernel invitado separados. No es, por sí mismo, un plano de control multiusuario endurecido:

• Los procesos CLI y VMM de smolvm se ejecutan con los permisos del usuario del host que los invoca. Esa cuenta de usuario, el sistema operativo del host, el backend del hipervisor, libkrun y smolvm forman parte de la base de computación confiable.
• Los directorios del host pasados con --volume se exponen intencionalmente al invitado con el acceso solicitado. No montes secretos ni rutas sensibles en una carga de trabajo no confiable.
• --ssh-agent no copia material de clave privada al invitado, pero concede al invitado acceso al socket del agente reenviado y, por tanto, la capacidad de solicitar firmas mientras la VM está en ejecución.
• La red está desactivada por defecto. Habilitar --net, el reenvío de puertos o los servicios del host amplía la superficie alcanzable de la carga de trabajo.
• En uso local independiente, el estado y los endpoints de control de smolvm están limitados al entorno del usuario que los invoca. Para co-inquilinos locales hostiles, añade separación de cuentas a nivel de host y confinamiento del SO alrededor del proceso VMM. Esta sección no describe el plano de control en la nube separado de smolmachines ni sus garantías de aislamiento entre inquilinos.
• Los archivos de lanzamiento publican sumas de comprobación SHA-256 y el instalador rechaza una discrepancia cuando el archivo de suma está disponible. Los lanzamientos no están firmados actualmente ni acompañados de atestaciones de procedencia, y el instalador permite la instalación cuando el archivo de suma no se puede descargar.

Trata a root en el invitado como no confiable. El límite de la VM limita su acceso directo al host, mientras que cada capacidad reenviada explícitamente, incluidos montajes, acceso a la red, puertos y acceso al agente SSH, pasa a formar parte de la autoridad de la carga de trabajo.

Comparación

Soporte de Plataformas

Limitaciones Conocidas

• La red es opcional (--net en machine create). Solo TCP/UDP, sin ICMP.
• Montajes de volúmenes: solo directorios (no archivos individuales). Montar en /workspace (-v /host/dir:/workspace) tiene prioridad sobre el workspace del disco de almacenamiento predeterminado — se usa tu directorio del host en su lugar.
• macOS: el binario debe estar firmado con los entitlements de Hypervisor.framework (com.apple.security.hypervisor). La versión publicada lo está; un binario re-firmado o recién compilado lo pierde silenciosamente y cada inicio de VM falla entonces con krun_start_enter returned: -22 (EINVAL). Vuelve a firmarlo (ad-hoc es suficiente): codesign --force --sign - --entitlements hv.entitlements <smolvm-bin> donde hv.entitlements es un plist que contiene <key>com.apple.security.hypervisor</key><true/>.
• --ssh-agent requiere un agente SSH ejecutándose en el host (SSH_AUTH_SOCK debe estar configurado).
• La aceleración GPU requiere libkrun compilado con GPU=1 y virglrenderer + un controlador Vulkan en el host (consulta Aceleración GPU abajo).
• Windows: --net funciona igual que en otras plataformas (virtio-net con reenvío de puertos entrantes; TSI para VMs solo de salida), al igual que machine exec / sesiones interactivas y machine stats. Aún no disponible en Windows: aceleración GPU y machine fork / instantáneas. Pack create necesita storage-template.ext4 / overlay-template.ext4 junto a smolvm.exe (Windows no tiene mkfs.ext4 en el host).

Aceleración GPU

smolvm expone la GPU del host a los invitados mediante virtio-gpu / Venus (Vulkan sobre virtio). Las cargas de trabajo invitadas ven un dispositivo Vulkan real; en Linux + Intel esto se renderiza como:

ANGLE (Intel, Vulkan 1.4 (Virtio-GPU Venus (Intel(R) UHD Graphics ...)), venus)

Requisitos del host

macOS — virglrenderer y MoltenVK están incluidos en la distribución de smolvm. No se necesitan instalaciones adicionales.

Linux — virglrenderer y un controlador Vulkan del host deben instalarse desde el gestor de paquetes del sistema:

virglrenderer depende de libEGL y libdrm de la pila de controladores GPU del host — estos son específicos del hardware y no se pueden incluir. Cualquier host Linux con capacidad GPU ya los tendrá instalados mediante su controlador GPU.

Uso

# CLI
smolvm machine run --gpu --image alpine -- vulkaninfo --summary

# Smolfile
# gpu = true
# gpu_vram = 2048   # MiB, predeterminado 4096

El cargador Vulkan del invitado debe apuntar al ICD virtio:

export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/virtio_icd.x86_64.json

Ejemplo de navegador headless

Consulta examples/headless-browser/ para una configuración funcional de Chromium usando ANGLE + Venus para WebGL acelerado por hardware dentro de una VM headless.

Remoting de API CUDA

--gpu y --cuda proporcionan interfaces diferentes. --gpu expone Vulkan mediante virtio-gpu / Venus; no proporciona CUDA. --cuda habilita el remoting de API CUDA: shims invitados sin controlador reenvían llamadas CUDA a través de vsock a un proceso del host, que las ejecuta mediante el controlador NVIDIA del host.

El remoting CUDA requiere una GPU NVIDIA y un controlador NVIDIA funcional en el host. No es paso de GPU (passthrough): el invitado no recibe ni el dispositivo físico ni un controlador NVIDIA.

Los hosts Linux con mucha actividad de fork deben usar un kernel que contenga la corrección KVM ascendente 916b7f4. Los kernels afectados pueden reportar intermitentemente ENOMEM en el primer KVM_RUN incluso con abundante memoria del host; smolvm reduce la exposición y reemplaza un worker fallido, pero la actualización del kernel es la corrección definitiva.

El límite de la VM sigue aislando la CPU, la memoria y el sistema de archivos de la carga de trabajo. El acceso a la GPU está mediado por procesos del host y la GPU compartida del host, por lo que el aislamiento de GPU sigue siendo a nivel de proceso en lugar de un límite de hardware o VM. No trates el remoting CUDA como un límite de aislamiento GPU multiusuario endurecido.

Consulta Acceso a GPU mediante remoting de API: cómo una microVM sin controlador ejecuta CUDA para conocer el diseño, las compensaciones y la comparación con el paso (passthrough).

Desarrollo

Consulta docs/DEVELOPMENT.md.

Apache-2.0 · hecho por @binsquare · twitter · github