smol machines

GPU Acceleration ​

Run GPU-accelerated workloads inside hardware-isolated microVMs. Enables Vulkan-based rendering, ML inference, and browser automation with access to the host GPU.

Quick Start ​

bash
# Headless Chromium screenshot with GPU
smolvm machine run --gpu --net --image fedora:42 -- bash -c '
  dnf install -y chromium-headless mesa-vulkan-drivers vulkan-tools
  /usr/lib64/chromium-browser/headless_shell \
    --no-sandbox --screenshot=/tmp/shot.png \
    --window-size=1920,1080 https://example.com'

Enable GPU ​

CLI ​

bash
smolvm machine run --gpu -- vulkaninfo
smolvm machine create my-vm --gpu --net

Smolfile ​

toml
image = "fedora:42"
gpu = true
net = true
cpus = 4
memory = 4096

SDK ​

typescript
const machine = await Machine.create({
  name: 'gpu-workload',
  resources: {
    cpus: 4,
    memoryMb: 4096,
    gpu: true
  }
});
python
config = MachineConfig(
    name="gpu-workload",
    resources=ResourceSpec(
        cpus=4,
        memory_mb=4096,
        gpu=True
    )
)

HTTP API ​

bash
curl -X POST http://localhost:8080/machines \
  -H 'Content-Type: application/json' \
  -d '{"name": "gpu-vm", "gpu": true, "network": true, "cpus": 4, "memoryMb": 4096}'

Packed Binary ​

GPU can be embedded in a .smolmachine:

toml
# Smolfile for packing
image = "fedora:42"
gpu = true
bash
smolvm pack create -s gpu.smolfile -o gpu-app
./gpu-app run -- vulkaninfo

Host Setup ​

macOS (Apple Silicon) ​

No host dependencies to install. virglrenderer and MoltenVK are bundled inside the smolvm distribution — GPU works out of the box.

The GPU pipeline on macOS: Guest Vulkan → Venus → MoltenVK → Metal → Apple GPU.

Guest requirement (macOS only): Standard Mesa has a page alignment bug on Apple Silicon. Install the patched Mesa inside Fedora guests:

bash
dnf copr enable slp/mesa-libkrun-vulkan
dnf install --allowerasing mesa-vulkan-drivers

Linux ​

bash
# Debian/Ubuntu
apt install virglrenderer0 mesa-vulkan-drivers

# Fedora
dnf install virglrenderer mesa-vulkan-drivers

No patched Mesa needed on Linux. Standard distro packages work.

Cloud (GCP, AWS) ​

On cloud GPU instances (NVIDIA T4, A100, L4, etc.):

bash
# Host VM setup
apt install virglrenderer0 nvidia-driver-XXX

# Then use smolvm normally
smolvm machine run --gpu --net --image fedora -- vulkaninfo

Requirements:

  • GPU instance type (e.g., GCP n1-standard-4 + NVIDIA T4)
  • Nested virtualization enabled (GCP: --enable-nested-virtualization)
  • Host NVIDIA/AMD driver installed
  • virglrenderer installed on the host VM

On non-GPU cloud instances, --gpu has no effect — there's no physical GPU to accelerate.

How It Works ​

Guest App (browser, ML framework)
    ↓
Mesa Venus driver (Vulkan inside VM)
    ↓  virtio-gpu transport
libkrun virtio-gpu device
    ↓
virglrenderer Venus (host)
    ↓
Host Vulkan driver
    ↓
Physical GPU (Apple Silicon / NVIDIA / AMD / Intel)

Each VM gets its own isolated GPU context. Multiple VMs can share the same physical GPU through Venus — each with separate Vulkan instances, no cross-VM data leakage.

Use Cases ​

Browser Automation (Playwright/Puppeteer) ​

bash
# Start browser with Chrome DevTools Protocol
smolvm machine create browser --gpu --net --image fedora:42 -p 9222:9222
smolvm machine start --name browser
smolvm machine exec --name browser -- bash -c '
  /usr/lib64/chromium-browser/headless_shell \
    --no-sandbox --remote-debugging-port=9222 \
    --remote-debugging-address=0.0.0.0 about:blank'

# Connect Playwright from host
# ws://localhost:9222

Each browser session runs in its own hardware-isolated microVM with GPU acceleration. Stronger isolation than Docker containers.

ML Inference ​

bash
smolvm machine run --gpu --net --image fedora:42 -- bash -c '
  pip install llama-cpp-python
  # llama.cpp uses Vulkan for GPU inference
  python3 -c "from llama_cpp import Llama; ..."'

Headless Screenshots ​

bash
smolvm machine run --gpu --net --image fedora:42 -- bash -c '
  /usr/lib64/chromium-browser/headless_shell \
    --no-sandbox --screenshot=/tmp/shot.png \
    --window-size=1920,1080 https://example.com'

Limitations ​

  • macOS: Requires patched Mesa in the guest (16KB page alignment)
  • No native Metal/CUDA in the VM — GPU access is through Vulkan only
  • No Apple Neural Engine — ANE is not virtualizable
  • Video decode: Software only (no VA-API passthrough yet)

Resource Options ​

OptionTypeDefaultDescription
gpubooleanfalseEnable GPU acceleration

GPU is opt-in. Without --gpu, no GPU device is created and the VM runs with zero GPU overhead.