{"id":42577648,"url":"https://github.com/smol-machines/smolvm","last_synced_at":"2026-07-07T14:52:25.293Z","repository":{"id":332587518,"uuid":"1119210021","full_name":"smol-machines/smolvm","owner":"smol-machines","description":"Tool to build \u0026 run portable, lightweight, self-contained virtual machines.","archived":false,"fork":false,"pushed_at":"2026-06-28T08:20:05.000Z","size":54158,"stargazers_count":3976,"open_issues_count":53,"forks_count":181,"subscribers_count":9,"default_branch":"main","last_synced_at":"2026-06-28T09:21:41.019Z","etag":null,"topics":["containers","crun","libkrun","microvm","rust","virtual-machine"],"latest_commit_sha":null,"homepage":"https://smolmachines.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smol-machines.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"BinSquare"}},"created_at":"2025-12-18T23:25:15.000Z","updated_at":"2026-06-28T07:52:06.000Z","dependencies_parsed_at":"2026-04-13T12:00:49.396Z","dependency_job_id":null,"html_url":"https://github.com/smol-machines/smolvm","commit_stats":null,"previous_names":["smol-machines/smolvm"],"tags_count":69,"template":false,"template_full_name":null,"purl":"pkg:github/smol-machines/smolvm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smol-machines%2Fsmolvm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smol-machines%2Fsmolvm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smol-machines%2Fsmolvm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smol-machines%2Fsmolvm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smol-machines","download_url":"https://codeload.github.com/smol-machines/smolvm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smol-machines%2Fsmolvm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35232326,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["containers","crun","libkrun","microvm","rust","virtual-machine"],"created_at":"2026-01-28T22:00:32.659Z","updated_at":"2026-07-07T14:52:25.265Z","avatar_url":"https://github.com/smol-machines.png","language":"Rust","funding_links":["https://github.com/sponsors/BinSquare"],"categories":["rust","Rust","MicroVMs","Virtual machines and microVM platforms","Sandboxing \u0026 Isolation"],"sub_categories":["Multiplatform"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.png\" alt=\"smol machines\" width=\"80\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://discord.gg/E5r8rEWY9J\"\u003e\u003cimg src=\"https://img.shields.io/badge/Discord-Join-5865F2?logo=discord\u0026logoColor=white\" alt=\"Discord\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/smol-machines/smolvm/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/smol-machines/smolvm?label=Release\" alt=\"Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/smol-machines/smolvm/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache_2.0-blue.svg\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nsmolvm\n======\n\nShip and run software with isolation by default.\n\nThis is a CLI tool that lets you:\n1. Manage and run custom Linux virtual machines locally with: sub-second cold start, cross-platform (macOS, Linux), elastic memory usage.\n2. Pack a stateful virtual machine into a single file (.smolmachine) to rehydrate on any supported platform.\n\nInstall\n-------\n\n```bash\n# install (macOS + Linux)\ncurl -sSL https://smolmachines.com/install.sh | bash\n\n# for coding agents — install + discover all commands\ncurl -sSL https://smolmachines.com/install.sh | bash \u0026\u0026 smolvm --help\n```\n\nOr download from [GitHub Releases](https://github.com/smol-machines/smolvm/releases), and place it into `~/.local/share/`.\n\nQuick Start\n-----------\n\n```bash\n# run a command in an ephemeral VM (cleaned up after exit)\nsmolvm machine run --net --image alpine -- sh -c \"echo 'Hello world from a microVM' \u0026\u0026 uname -a\"\n\n# interactive shell\nsmolvm machine run --net -it --image alpine -- /bin/sh\n# inside the VM: apk add sl \u0026\u0026 sl \u0026\u0026 exit\n```\n\nUse This For\n------------\n\n**Sandbox untrusted code** — run untrusted programs in a hardware-isolated VM. Host filesystem, network, and credentials are separated by a hypervisor boundary.\n\n```bash\n# network is off by default — untrusted code can't phone home\nsmolvm machine run --image alpine -- nslookup example.com\n# fails — no network access\n\n# lock down egress — only allow specific hosts\nsmolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://registry.npmjs.org\n# works — allowed host\n\nsmolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://google.com\n# fails — not in allow list\n```\n\n**Pack into portable executables** — turn any workload into a self-contained binary. All dependencies are pre-baked — no install step, no runtime downloads, boots in \u003c200ms.\n\n```bash\nsmolvm pack create --image python:3.12-alpine -o ./python312\n./python312 run -- python3 --version\n# Python 3.12.x — isolated, no pyenv/venv/conda needed\n```\n\n**Persistent machines for development** — create, stop, start. Installed packages survive restarts.\n\n```bash\nsmolvm machine create --net myvm\nsmolvm machine start --name myvm\nsmolvm machine exec --name myvm -- apk add sl\nsmolvm machine exec --name myvm -it -- /bin/sh\n# inside: sl, ls, uname -a — type 'exit' to leave\nsmolvm machine stop --name myvm\n```\n\n**Use git and SSH without exposing keys** — forward your host SSH agent into the VM. Private keys never enter the guest — the hypervisor enforces this. Requires an SSH agent running on your host (`ssh-add -l` to check).\n\n```bash\nsmolvm machine run --ssh-agent --net --image alpine -- sh -c \"apk add -q openssh-client \u0026\u0026 ssh-add -l\"\n# lists your host keys, but they can't be extracted from inside the VM\n\nsmolvm machine exec --name myvm -- git clone git@github.com:org/private-repo.git\n```\n\n**Declare environments with a Smolfile** — reproducible VM config in a simple TOML file.\n\n```toml\nimage = \"python:3.12-alpine\"\nnet = true\n\n[network]\nallow_hosts = [\"api.stripe.com\", \"db.example.com\"]\n\n[dev]\ninit = [\"pip install -r requirements.txt\"]\nvolumes = [\"./src:/app\"]\n\n[auth]\nssh_agent = true\n```\n\n```bash\nsmolvm machine create myvm -s Smolfile\nsmolvm machine start --name myvm\n```\n\nMore examples: [python](https://github.com/smol-machines/smolvm/tree/main/examples/python-app) · [node](https://github.com/smol-machines/smolvm/tree/main/examples/node-app) · [doom](https://github.com/smol-machines/smolvm/tree/main/examples/doom-web)\n\nHow It Works\n------------\n\nEach workload gets real hardware isolation — its own kernel on [Hypervisor.framework](https://developer.apple.com/documentation/hypervisor) (macOS) or KVM (Linux). [libkrun](https://github.com/containers/libkrun) VMM with custom kernel: [libkrunfw](https://github.com/smol-machines/libkrunfw). Pack it into a `.smolmachine` and it runs anywhere the host architecture matches, with zero dependencies.\n\nImages use the [OCI](https://opencontainers.org/) format — the same open standard Docker uses. Any image on Docker Hub, ghcr.io, or other OCI registries can be pulled and booted as a microVM. No Docker daemon required.\n\nDefaults: 4 vCPUs, 8 GiB RAM. Memory is elastic via virtio balloon — the host only commits what the guest actually uses and reclaims the rest automatically. vCPU threads sleep in the hypervisor when idle, so over-provisioning has near-zero cost. Override with `--cpus` and `--mem`.\n\nComparison\n----------\n\n|                     | smolvm | Containers | Colima | QEMU | Firecracker | Kata |\n|---------------------|--------|------------|--------|------|-------------|------|\n| Isolation           | VM per workload | Namespace (shared kernel) | Namespace (1 VM) | Separate VM | Separate VM | VM per container |\n| Boot time           | \u003c200ms | ~100ms | ~seconds | ~15-30s | \u003c125ms | ~500ms |\n| Architecture        | Library (libkrun) | Daemon | Daemon (in VM) | Process | Process | Runtime stack |\n| Per-workload VMs    | Yes | No | No (shared) | Yes | Yes | Yes |\n| macOS native        | Yes | Via Docker VM | Yes (krunkit) | Yes | No | No |\n| Embeddable SDK      | Yes | No | No | No | No | No |\n| Portable artifacts  | `.smolmachine` | Images (need daemon) | No | No | No | No |\n\nPlatform Support\n----------------\n\n| Host | Guest | Requirements |\n|------|-------|-------------|\n| macOS Apple Silicon | arm64 Linux | macOS 11+ |\n| macOS Intel | x86_64 Linux | macOS 11+ (untested) |\n| Linux x86_64 | x86_64 Linux | KVM (`/dev/kvm`) |\n| Linux aarch64 | aarch64 Linux | KVM (`/dev/kvm`) |\n\nKnown Limitations\n-----------------\n\n* Network is opt-in (`--net` on `machine create`). TCP/UDP only, no ICMP.\n* Volume mounts: directories only (no single files). Mounting at `/workspace` (`-v /host/dir:/workspace`) takes priority over the default storage-disk workspace — your host directory is used instead.\n* macOS: binary must be signed with Hypervisor.framework entitlements.\n* `--ssh-agent` requires an SSH agent running on the host (`SSH_AUTH_SOCK` must be set).\n* GPU acceleration requires libkrun built with `GPU=1` and virglrenderer + a Vulkan driver on the host (see [GPU Acceleration](#gpu-acceleration) below).\n\nGPU Acceleration\n----------------\n\nsmolvm exposes the host GPU to guests via **virtio-gpu / Venus** (Vulkan-over-virtio). Guest workloads see a real Vulkan device; on Linux + Intel this renders as:\n\n```\nANGLE (Intel, Vulkan 1.4 (Virtio-GPU Venus (Intel(R) UHD Graphics ...)), venus)\n```\n\n### Host requirements\n\n**macOS** — virglrenderer and MoltenVK are bundled in the smolvm distribution. No extra installs needed.\n\n**Linux** — virglrenderer and a host Vulkan driver must be installed from the system package manager:\n\n| Distro | Packages |\n|--------|----------|\n| Alpine | `apk add virglrenderer mesa-vulkan-intel` (or `mesa-vulkan-ati` for AMD) |\n| Debian/Ubuntu | `apt install virglrenderer0 mesa-vulkan-drivers` |\n\n\u003e virglrenderer depends on libEGL and libdrm from the host GPU driver stack — these are hardware-specific and cannot be bundled. Any GPU-capable Linux host will already have them installed via its GPU driver.\n\n### Usage\n\n```bash\n# CLI\nsmolvm machine run --gpu --image alpine -- vulkaninfo --summary\n\n# Smolfile\n# gpu = true\n# gpu_vram = 2048   # MiB, default 4096\n```\n\nThe guest Vulkan loader must be pointed at the virtio ICD:\n\n```bash\nexport VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/virtio_icd.x86_64.json\n```\n\n### Headless browser example\n\nSee [`examples/headless-browser/`](examples/headless-browser/) for a working Chromium setup using ANGLE + Venus for hardware-accelerated WebGL inside a headless VM.\n\nDevelopment\n-----------\n\nSee [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).\n\n[Apache-2.0](LICENSE) · made by [@binsquare](https://github.com/BinSquare) · [twitter](https://x.com/binsquares) · [github](https://github.com/smol-machines/smolvm)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmol-machines%2Fsmolvm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmol-machines%2Fsmolvm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmol-machines%2Fsmolvm/lists"}