Guide
VM Lifecycle
Create, start, stop, and remove microVMs
vmsan provides commands to manage the full lifecycle of Firecracker microVMs.
Create a new VM
Use vmsan create to spin up a new microVM:
vmsan create --runtime node22 --memory 512 --vcpus 2
You can configure the VM with these flags:
| Flag | Default | Description |
|---|---|---|
--vcpus | 1 | Number of vCPUs |
--memory | 128 | Memory in MiB |
--runtime | base | Runtime label (base, node22, node24, python3.13) |
--disk | 10gb | Root disk size |
--timeout | none | Auto-shutdown timeout (e.g. 1h, 30m) |
--connect | false | Automatically connect to the shell after creation |
--project | none | Project label for grouping VMs |
--snapshot | none | Snapshot ID to restore from |
Add
--connect to immediately open a shell session after the VM is created.Create a VM from a Docker image
Build a root filesystem from any Docker or OCI image:
vmsan create --from-image node:22-alpine
See the Docker Images guide for more details.
List all VMs
vmsan list
Use the alias vmsan ls for a shorter command. Add --json for structured output.
Start a stopped VM
vmsan start <vm-id>
Stop a running VM
vmsan stop <vm-id>
Remove a VM
vmsan remove <vm-id>
Use the alias vmsan rm for a shorter command.
Removing a VM deletes its chroot directory and state file permanently.
Execute commands
Run a command inside a VM and stream the output:
vmsan exec <vm-id> ls -la /tmp
Use -i for interactive mode (full PTY), --sudo to run as root, -w to set the working directory, and -e to inject environment variables:
# Interactive session
vmsan exec -i <vm-id> bash
# Run as root
vmsan exec --sudo <vm-id> apt-get update
# With working directory and env
vmsan exec -w /app -e NODE_ENV=production <vm-id> node server.js
Connect to a running VM
Open an interactive shell session:
vmsan connect <vm-id>
This opens a WebSocket PTY connection to the in-VM agent, providing a full terminal experience.