Getting Started
Installation
How to install vmsan and its dependencies
Prerequisites
- Linux (x86_64 or aarch64) with KVM support
- Root/sudo access (required for TAP networking and jailer)
- Docker (only for source installs, local runtime rebuilds, and
--from-image)
Install Firecracker, kernel, and rootfs
Run the install script to download Firecracker, a Linux kernel, the Ubuntu 24.04 root filesystem, and the built-in runtime images into ~/.vmsan/:
curl -fsSL https://vmsan.dev/install | bash
This installs:
- Firecracker + Jailer (latest release)
- Linux kernel (vmlinux 6.1)
- Ubuntu 24.04 rootfs (converted from squashfs to ext4)
- Runtime images (
node22,node24,python3.13) downloaded as prebuilt artifacts
Standard release installs download built-in runtimes from
https://artifacts.vmsan.dev/ and do not require Docker. Source installs still build runtimes locally, and --from-image still requires Docker.Install the vmsan CLI
bun add -g vmsan
npm install -g vmsan
pnpm add -g vmsan
yarn global add vmsan
Build the in-VM agent
The Go agent runs inside each VM and handles shell access, file operations, and command execution.
Release installs download vmsan-agent automatically. For source installs:
cd agent
make install
cd ..
Verify the installation
vmsan --help
You should see a list of available commands.
For staging or recovery testing, you can override the runtime manifest:To force local runtime builds during a release install:
curl -fsSL https://vmsan.dev/install | \
VMSAN_RUNTIME_MANIFEST_URL=https://artifacts.vmsan.dev/runtimes/channels/staging.json bash
curl -fsSL https://vmsan.dev/install | \
VMSAN_FORCE_LOCAL_RUNTIME_BUILD=1 bash
Uninstall
To remove Firecracker, the kernel, and rootfs from ~/.vmsan/:
curl -fsSL https://vmsan.dev/install | bash -s -- --uninstall