SmolVM runs your code inside its own virtual machine, completely separated from your host. This page explains what that isolation covers, where the boundaries are, and how to keep things safe.
How isolation works
Each sandbox runs in a microVM — a lightweight virtual machine backed by hardware virtualization (KVM on Linux, HVF on macOS). Unlike containers, which share the host kernel, microVMs give every sandbox its own kernel. Breaking out of a microVM requires a hypervisor exploit, not just a kernel vulnerability.
| Feature | Containers | SmolVM (microVMs) |
|---|
| Kernel | Shared with host | Isolated kernel per VM |
| Syscall interface | Direct to host kernel | Through KVM hypervisor |
| Attack surface | Entire host kernel | Virtualized hardware only |
| Escape difficulty | Kernel exploits | Hardware virtualization bypass |
| Boot time | Milliseconds | Sub-second |
- Strong isolation — Firecracker microVMs use hardware virtualization (KVM), making it much harder for code to escape to your host
- Controlled networking — you can restrict or monitor what the sandbox can reach on the internet
- Ephemeral environments — spin up a fresh sandbox for every task and destroy it immediately, so nothing persists
What SmolVM protects
Host system
Malicious guest code cannot:
- Access host filesystem (except via shared volumes)
- Read host memory
- Interfere with other VMs
- Access host network interfaces directly
- Execute privileged operations on the host
Network isolation
By default, sandboxes are isolated from each other:
# This network rule prevents VM-to-VM traffic
# From network.py:469-472
iifname "tap*" oifname "tap*" counter drop
- Access the internet via NAT (configurable)
- Be accessed from the host via port forwarding
- Cannot directly communicate with other sandboxes
Resource limits
Each sandbox has dedicated, capped resources:
from smolvm import VMConfig
config = VMConfig(
vcpu_count=2, # Max 2 CPUs
mem_size_mib=512 # Max 512 MiB RAM
)
What SmolVM does not protect
SmolVM provides isolation, not complete security. Understand these limitations:
Outbound network access
SmolVM assumes the host network is trusted. Guests can:
- Make outbound network requests (unless restricted)
- Access any internet service
- Download and execute code from the internet
Data exfiltration
If a sandbox has network access, malicious code can:
- Send data to external servers
- Establish reverse shells
- Participate in botnets
Mitigation: Use firewall rules or network policies to restrict outbound access.
Resource exhaustion
A malicious guest can:
- Consume all allocated CPU and memory
- Fill the allocated disk
- Generate high network traffic
Mitigation: Set appropriate resource limits and monitor usage.
SSH trust model
SmolVM currently prioritizes zero-touch VM access for local agent workflows. Read this section carefully.
AutoAddPolicy for SSH connections, which means it accepts unknown host keys on first connection. This keeps setup simple for local use, but it can allow man-in-the-middle attacks on untrusted networks.
Treat SmolVM as a local-only runtime by default. Do not expose sandbox SSH ports to public or untrusted networks without additional controls.
Recommended practices
Follow these practices to use SmolVM securely:
Local-only usage
- Run SmolVM on developer machines or trusted CI runners
- Do not expose guest SSH endpoints to public or untrusted networks
Network controls
If your environment requires strict host identity validation:
- Use private networking with firewall restrictions
- Deploy bastion or proxy hosts
- Add SSH key pinning at your deployment layer
Trusted networks only
# Good: Local development
with SmolVM() as vm:
result = vm.run("echo 'Safe on localhost'")
# Bad: Exposing to untrusted networks
# DO NOT expose VM SSH ports publicly without additional controls
Disk isolation
Isolated mode (default)
SmolVM defaults to disk_mode="isolated", creating a per-VM rootfs clone:
from smolvm import VMConfig
# Each VM gets its own disk copy
config = VMConfig(disk_mode="isolated")
- Complete filesystem isolation
- No state leakage between VMs
- Safe for untrusted code
Trade-offs:
- Additional disk space per VM
- Slight creation overhead for copying rootfs
Shared mode
For trusted workloads that need persistent storage:
config = VMConfig(disk_mode="shared")
Shared mode means all VMs boot from the same rootfs. Use only for trusted workloads where you need state persistence.
Disk retention
Control whether isolated disks are kept after VM deletion:
config = VMConfig(
disk_mode="isolated",
retain_disk_on_delete=True # Keep disk for later reuse
)
Environment variables
SmolVM can inject environment variables into VMs:
from smolvm import SmolVM
with SmolVM() as vm:
vm.set_env_vars({
"API_KEY": "sk-...",
"DEBUG": "1"
})
Environment variables are persisted in /etc/profile.d/smolvm_env.sh in the guest. Do not inject highly sensitive secrets if the VM is shared or persistent.
Best practices
- Use ephemeral VMs for sensitive operations
- Rotate secrets after VM deletion
- Prefer isolated disk mode for untrusted code
- Consider using secret management services
Vulnerability reporting
Supported versions
SmolVM is currently pre-1.0. Security fixes are prioritized for:
| Version / Branch | Supported |
|---|
| Latest release tag | ✅ |
main branch | ✅ (best effort) |
| Older release tags | ❌ |
Reporting process
Do not open public GitHub issues for suspected vulnerabilities.
What to include
Please include:
- Clear description of the vulnerability and impact
- Affected version/commit and host environment (OS, architecture)
- Reproduction steps or proof-of-concept
- Expected vs. actual behavior
- Any suggested mitigation
Response expectations
As a small team, reports are handled as capacity allows. Non-binding targets:
- Acknowledge report within 3 business days
- Triage and severity assessment within 7 business days
- Provide periodic updates when possible
Disclosure policy
SmolVM follows coordinated disclosure:
- Please allow reasonable time for a fix before public disclosure
- Security advisories may be published for confirmed issues
- Reporters are credited (unless anonymous credit is requested)
Scope notes
This security policy covers vulnerabilities in SmolVM’s code and release artifacts.
Out of scope
(unless caused by SmolVM code):
- Vulnerabilities in third-party dependencies/upstream projects
- Host misconfiguration outside documented SmolVM setup
- Security findings without a realistic exploit path or impact
Security checklist
Before deploying SmolVM:
Next steps