Getting Started
Installation
How to install vmsan and its dependencies
Prerequisites
- Linux (x86_64 or aarch64) with KVM support
- Bun >= 1.2
- Go >= 1.22 (to build the in-VM agent)
- Root/sudo access (required for TAP networking and jailer)
squashfs-tools(for rootfs conversion during install)
Install Firecracker, kernel, and rootfs
Run the install script to download Firecracker, a Linux kernel, and the Ubuntu 24.04 root filesystem 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)
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:
cd agent
make install
cd ..
Verify the installation
vmsan --help
You should see a list of available commands.
You can also link a local development build globally by running
bun link from the project root.Uninstall
To remove Firecracker, the kernel, and rootfs from ~/.vmsan/:
curl -fsSL https://vmsan.dev/install | bash -s -- --uninstall